tauthon/tauthon2.7
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Import Upstream version 2.7.18

Browse Source
This commit is contained in:
geos_one
2025-08-15 16:28:06 +02:00
commit ba1f69ab39
4521 changed files with 1778434 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

446
Doc/library/2to3.rst Normal file
View File

@@ -0,0 +1,446 @@
.. _2to3-reference:
2to3 - Automated Python 2 to 3 code translation
===============================================
.. sectionauthor:: Benjamin Peterson <benjamin@python.org>
2to3 is a Python program that reads Python 2.x source code and applies a series
of *fixers* to transform it into valid Python 3.x code. The standard library
contains a rich set of fixers that will handle almost all code. 2to3 supporting
library :mod:`lib2to3` is, however, a flexible and generic library, so it is
possible to write your own fixers for 2to3. :mod:`lib2to3` could also be
adapted to custom applications in which Python code needs to be edited
automatically.
.. _2to3-using:
Using 2to3
----------
2to3 will usually be installed with the Python interpreter as a script. It is
also located in the :file:`Tools/scripts` directory of the Python root.
2to3's basic arguments are a list of files or directories to transform. The
directories are recursively traversed for Python sources.
Here is a sample Python 2.x source file, :file:`example.py`::
def greet(name):
print "Hello, {0}!".format(name)
print "What's your name?"
name = raw_input()
greet(name)
It can be converted to Python 3.x code via 2to3 on the command line:
.. code-block:: shell-session
$ 2to3 example.py
A diff against the original source file is printed. 2to3 can also write the
needed modifications right back to the source file. (A backup of the original
file is made unless :option:`!-n` is also given.) Writing the changes back is
enabled with the :option:`!-w` flag:
.. code-block:: shell-session
$ 2to3 -w example.py
After transformation, :file:`example.py` looks like this::
def greet(name):
print("Hello, {0}!".format(name))
print("What's your name?")
name = input()
greet(name)
Comments and exact indentation are preserved throughout the translation process.
By default, 2to3 runs a set of :ref:`predefined fixers <2to3-fixers>`. The
:option:`!-l` flag lists all available fixers. An explicit set of fixers to run
can be given with :option:`!-f`. Likewise the :option:`!-x` explicitly disables a
fixer. The following example runs only the ``imports`` and ``has_key`` fixers:
.. code-block:: shell-session
$ 2to3 -f imports -f has_key example.py
This command runs every fixer except the ``apply`` fixer:
.. code-block:: shell-session
$ 2to3 -x apply example.py
Some fixers are *explicit*, meaning they aren't run by default and must be
listed on the command line to be run. Here, in addition to the default fixers,
the ``idioms`` fixer is run:
.. code-block:: shell-session
$ 2to3 -f all -f idioms example.py
Notice how passing ``all`` enables all default fixers.
Sometimes 2to3 will find a place in your source code that needs to be changed,
but 2to3 cannot fix automatically. In this case, 2to3 will print a warning
beneath the diff for a file. You should address the warning in order to have
compliant 3.x code.
2to3 can also refactor doctests. To enable this mode, use the :option:`!-d`
flag. Note that *only* doctests will be refactored. This also doesn't require
the module to be valid Python. For example, doctest like examples in a reST
document could also be refactored with this option.
The :option:`!-v` option enables output of more information on the translation
process.
Since some print statements can be parsed as function calls or statements, 2to3
cannot always read files containing the print function. When 2to3 detects the
presence of the ``from __future__ import print_function`` compiler directive, it
modifies its internal grammar to interpret :func:`print` as a function. This
change can also be enabled manually with the :option:`!-p` flag. Use
:option:`!-p` to run fixers on code that already has had its print statements
converted.
The :option:`!-o` or :option:`!--output-dir` option allows specification of an
alternate directory for processed output files to be written to. The
:option:`!-n` flag is required when using this as backup files do not make sense
when not overwriting the input files.
.. versionadded:: 2.7.3
The :option:`!-o` option was added.
The :option:`!-W` or :option:`!--write-unchanged-files` flag tells 2to3 to always
write output files even if no changes were required to the file. This is most
useful with :option:`!-o` so that an entire Python source tree is copied with
translation from one directory to another.
This option implies the :option:`!-w` flag as it would not make sense otherwise.
.. versionadded:: 2.7.3
The :option:`!-W` flag was added.
The :option:`!--add-suffix` option specifies a string to append to all output
filenames. The :option:`!-n` flag is required when specifying this as backups
are not necessary when writing to different filenames. Example:
.. code-block:: shell-session
$ 2to3 -n -W --add-suffix=3 example.py
Will cause a converted file named ``example.py3`` to be written.
.. versionadded:: 2.7.3
The :option:`!--add-suffix` option was added.
To translate an entire project from one directory tree to another use:
.. code-block:: shell-session
$ 2to3 --output-dir=python3-version/mycode -W -n python2-version/mycode
.. _2to3-fixers:
Fixers
------
Each step of transforming code is encapsulated in a fixer. The command ``2to3
-l`` lists them. As :ref:`documented above <2to3-using>`, each can be turned on
and off individually. They are described here in more detail.
.. 2to3fixer:: apply
Removes usage of :func:`apply`. For example ``apply(function, *args,
**kwargs)`` is converted to ``function(*args, **kwargs)``.
.. 2to3fixer:: asserts
Replaces deprecated :mod:`unittest` method names with the correct ones.
================================ ==========================================
From To
================================ ==========================================
``failUnlessEqual(a, b)`` :meth:`assertEqual(a, b)
<unittest.TestCase.assertEqual>`
``assertEquals(a, b)`` :meth:`assertEqual(a, b)
<unittest.TestCase.assertEqual>`
``failIfEqual(a, b)`` :meth:`assertNotEqual(a, b)
<unittest.TestCase.assertNotEqual>`
``assertNotEquals(a, b)`` :meth:`assertNotEqual(a, b)
<unittest.TestCase.assertNotEqual>`
``failUnless(a)`` :meth:`assertTrue(a)
<unittest.TestCase.assertTrue>`
``assert_(a)`` :meth:`assertTrue(a)
<unittest.TestCase.assertTrue>`
``failIf(a)`` :meth:`assertFalse(a)
<unittest.TestCase.assertFalse>`
``failUnlessRaises(exc, cal)`` :meth:`assertRaises(exc, cal)
<unittest.TestCase.assertRaises>`
``failUnlessAlmostEqual(a, b)`` :meth:`assertAlmostEqual(a, b)
<unittest.TestCase.assertAlmostEqual>`
``assertAlmostEquals(a, b)`` :meth:`assertAlmostEqual(a, b)
<unittest.TestCase.assertAlmostEqual>`
``failIfAlmostEqual(a, b)`` :meth:`assertNotAlmostEqual(a, b)
<unittest.TestCase.assertNotAlmostEqual>`
``assertNotAlmostEquals(a, b)`` :meth:`assertNotAlmostEqual(a, b)
<unittest.TestCase.assertNotAlmostEqual>`
================================ ==========================================
.. 2to3fixer:: basestring
Converts :class:`basestring` to :class:`str`.
.. 2to3fixer:: buffer
Converts :class:`buffer` to :class:`memoryview`. This fixer is optional
because the :class:`memoryview` API is similar but not exactly the same as
that of :class:`buffer`.
.. 2to3fixer:: dict
Fixes dictionary iteration methods. :meth:`dict.iteritems` is converted to
:meth:`dict.items`, :meth:`dict.iterkeys` to :meth:`dict.keys`, and
:meth:`dict.itervalues` to :meth:`dict.values`. Similarly,
:meth:`dict.viewitems`, :meth:`dict.viewkeys` and :meth:`dict.viewvalues` are
converted respectively to :meth:`dict.items`, :meth:`dict.keys` and
:meth:`dict.values`. It also wraps existing usages of :meth:`dict.items`,
:meth:`dict.keys`, and :meth:`dict.values` in a call to :class:`list`.
.. 2to3fixer:: except
Converts ``except X, T`` to ``except X as T``.
.. 2to3fixer:: exec
Converts the :keyword:`exec` statement to the :func:`exec` function.
.. 2to3fixer:: execfile
Removes usage of :func:`execfile`. The argument to :func:`execfile` is
wrapped in calls to :func:`open`, :func:`compile`, and :func:`exec`.
.. 2to3fixer:: exitfunc
Changes assignment of :attr:`sys.exitfunc` to use of the :mod:`atexit`
module.
.. 2to3fixer:: filter
Wraps :func:`filter` usage in a :class:`list` call.
.. 2to3fixer:: funcattrs
Fixes function attributes that have been renamed. For example,
``my_function.func_closure`` is converted to ``my_function.__closure__``.
.. 2to3fixer:: future
Removes ``from __future__ import new_feature`` statements.
.. 2to3fixer:: getcwdu
Renames :func:`os.getcwdu` to :func:`os.getcwd`.
.. 2to3fixer:: has_key
Changes ``dict.has_key(key)`` to ``key in dict``.
.. 2to3fixer:: idioms
This optional fixer performs several transformations that make Python code
more idiomatic. Type comparisons like ``type(x) is SomeClass`` and
``type(x) == SomeClass`` are converted to ``isinstance(x, SomeClass)``.
``while 1`` becomes ``while True``. This fixer also tries to make use of
:func:`sorted` in appropriate places. For example, this block ::
L = list(some_iterable)
L.sort()
is changed to ::
L = sorted(some_iterable)
.. 2to3fixer:: import
Detects sibling imports and converts them to relative imports.
.. 2to3fixer:: imports
Handles module renames in the standard library.
.. 2to3fixer:: imports2
Handles other modules renames in the standard library. It is separate from
the :2to3fixer:`imports` fixer only because of technical limitations.
.. 2to3fixer:: input
Converts ``input(prompt)`` to ``eval(input(prompt))``.
.. 2to3fixer:: intern
Converts :func:`intern` to :func:`sys.intern`.
.. 2to3fixer:: isinstance
Fixes duplicate types in the second argument of :func:`isinstance`. For
example, ``isinstance(x, (int, int))`` is converted to ``isinstance(x,
(int))``.
.. 2to3fixer:: itertools_imports
Removes imports of :func:`itertools.ifilter`, :func:`itertools.izip`, and
:func:`itertools.imap`. Imports of :func:`itertools.ifilterfalse` are also
changed to :func:`itertools.filterfalse`.
.. 2to3fixer:: itertools
Changes usage of :func:`itertools.ifilter`, :func:`itertools.izip`, and
:func:`itertools.imap` to their built-in equivalents.
:func:`itertools.ifilterfalse` is changed to :func:`itertools.filterfalse`.
.. 2to3fixer:: long
Renames :class:`long` to :class:`int`.
.. 2to3fixer:: map
Wraps :func:`map` in a :class:`list` call. It also changes ``map(None, x)``
to ``list(x)``. Using ``from future_builtins import map`` disables this
fixer.
.. 2to3fixer:: metaclass
Converts the old metaclass syntax (``__metaclass__ = Meta`` in the class
body) to the new (``class X(metaclass=Meta)``).
.. 2to3fixer:: methodattrs
Fixes old method attribute names. For example, ``meth.im_func`` is converted
to ``meth.__func__``.
.. 2to3fixer:: ne
Converts the old not-equal syntax, ``<>``, to ``!=``.
.. 2to3fixer:: next
Converts the use of iterator's :meth:`~iterator.next` methods to the
:func:`next` function. It also renames :meth:`~iterator.next` methods to
:meth:`~iterator.__next__`.
.. 2to3fixer:: nonzero
Renames :meth:`__nonzero__` to :meth:`~object.__bool__`.
.. 2to3fixer:: numliterals
Converts octal literals into the new syntax.
.. 2to3fixer:: paren
Add extra parenthesis where they are required in list comprehensions. For
example, ``[x for x in 1, 2]`` becomes ``[x for x in (1, 2)]``.
.. 2to3fixer:: print
Converts the :keyword:`print` statement to the :func:`print` function.
.. 2to3fixer:: raise
Converts ``raise E, V`` to ``raise E(V)``, and ``raise E, V, T`` to ``raise
E(V).with_traceback(T)``. If ``E`` is a tuple, the translation will be
incorrect because substituting tuples for exceptions has been removed in Python 3.
.. 2to3fixer:: raw_input
Converts :func:`raw_input` to :func:`input`.
.. 2to3fixer:: reduce
Handles the move of :func:`reduce` to :func:`functools.reduce`.
.. 2to3fixer:: renames
Changes :data:`sys.maxint` to :data:`sys.maxsize`.
.. 2to3fixer:: repr
Replaces backtick repr with the :func:`repr` function.
.. 2to3fixer:: set_literal
Replaces use of the :class:`set` constructor with set literals. This fixer
is optional.
.. 2to3fixer:: standarderror
Renames :exc:`StandardError` to :exc:`Exception`.
.. 2to3fixer:: sys_exc
Changes the deprecated :data:`sys.exc_value`, :data:`sys.exc_type`,
:data:`sys.exc_traceback` to use :func:`sys.exc_info`.
.. 2to3fixer:: throw
Fixes the API change in generator's :meth:`throw` method.
.. 2to3fixer:: tuple_params
Removes implicit tuple parameter unpacking. This fixer inserts temporary
variables.
.. 2to3fixer:: types
Fixes code broken from the removal of some members in the :mod:`types`
module.
.. 2to3fixer:: unicode
Renames :class:`unicode` to :class:`str`.
.. 2to3fixer:: urllib
Handles the rename of :mod:`urllib` and :mod:`urllib2` to the :mod:`urllib`
package.
.. 2to3fixer:: ws_comma
Removes excess whitespace from comma separated items. This fixer is
optional.
.. 2to3fixer:: xrange
Renames :func:`xrange` to :func:`range` and wraps existing :func:`range`
calls with :class:`list`.
.. 2to3fixer:: xreadlines
Changes ``for x in file.xreadlines()`` to ``for x in file``.
.. 2to3fixer:: zip
Wraps :func:`zip` usage in a :class:`list` call. This is disabled when
``from future_builtins import zip`` appears.
:mod:`lib2to3` - 2to3's library
-------------------------------
.. module:: lib2to3
:synopsis: the 2to3 library
.. moduleauthor:: Guido van Rossum
.. moduleauthor:: Collin Winter
.. moduleauthor:: Benjamin Peterson <benjamin@python.org>
.. note::
The :mod:`lib2to3` API should be considered unstable and may change
drastically in the future.
.. XXX What is the public interface anyway?

44
Doc/library/__builtin__.rst Normal file
View File

@@ -0,0 +1,44 @@
: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 :ref:`built-in-funcs` and :ref:`built-in-consts` for
documentation.
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()
# ...
.. impl-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:`~object.__dict__` attribute. Since
this is an implementation detail, it may not be used by alternate
implementations of Python.

94
Doc/library/__future__.rst Normal file
View File

@@ -0,0 +1,94 @@
:mod:`__future__` --- Future statement definitions
==================================================
.. module:: __future__
:synopsis: Future statement definitions
**Source code:** :source:`Lib/__future__.py`
--------------
: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 :ref:`future statements <future>` 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 programmatically 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 built-in 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__`. Since its
introduction in Python 2.1 the following features have found their way into the
language using this mechanism:
+------------------+-------------+--------------+---------------------------------------------+
| feature | optional in | mandatory in | effect |
+==================+=============+==============+=============================================+
| nested_scopes | 2.1.0b1 | 2.2 | :pep:`227`: |
| | | | *Statically Nested Scopes* |
+------------------+-------------+--------------+---------------------------------------------+
| generators | 2.2.0a1 | 2.3 | :pep:`255`: |
| | | | *Simple Generators* |
+------------------+-------------+--------------+---------------------------------------------+
| division | 2.2.0a2 | 3.0 | :pep:`238`: |
| | | | *Changing the Division Operator* |
+------------------+-------------+--------------+---------------------------------------------+
| absolute_import | 2.5.0a1 | 3.0 | :pep:`328`: |
| | | | *Imports: Multi-Line and Absolute/Relative* |
+------------------+-------------+--------------+---------------------------------------------+
| with_statement | 2.5.0a1 | 2.6 | :pep:`343`: |
| | | | *The "with" Statement* |
+------------------+-------------+--------------+---------------------------------------------+
| print_function | 2.6.0a2 | 3.0 | :pep:`3105`: |
| | | | *Make print a function* |
+------------------+-------------+--------------+---------------------------------------------+
| unicode_literals | 2.6.0a2 | 3.0 | :pep:`3112`: |
| | | | *Bytes literals in Python 3000* |
+------------------+-------------+--------------+---------------------------------------------+
.. seealso::
:ref:`future`
How the compiler treats future imports.

17
Doc/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()

716
Doc/library/_winreg.rst Normal file
View File

@@ -0,0 +1,716 @@
:mod:`_winreg` --- Windows registry access
==========================================
.. module:: _winreg
:platform: Windows
:synopsis: Routines and objects for manipulating the Windows registry.
.. sectionauthor:: Mark Hammond <MarkH@ActiveState.com>
.. note::
The :mod:`_winreg` module has been renamed to :mod:`winreg` in Python 3.
The :term:`2to3` tool will automatically adapt imports when converting your
sources to Python 3.
.. versionadded:: 2.0
These functions expose the Windows registry API to Python. Instead of using an
integer as the registry handle, a :ref:`handle object <handle-object>` is used
to ensure that the handles are closed correctly, even if the programmer neglects
to explicitly close them.
This module offers the following functions:
.. function:: CloseKey(hkey)
Closes a previously opened registry key. The *hkey* argument specifies a
previously opened key.
.. note::
If *hkey* is not closed using this method (or via :meth:`hkey.Close() <PyHKEY.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 :ref:`handle object <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, a
:exc:`WindowsError` exception is raised.
.. function:: CreateKey(key, sub_key)
Creates or opens the specified key, returning a
:ref:`handle object <handle-object>`.
*key* is an already open key, or one of the predefined
:ref:`HKEY_* constants <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, a
:exc:`WindowsError` exception is raised.
.. function:: CreateKeyEx(key, sub_key[, res[, sam]])
Creates or opens the specified key, returning a
:ref:`handle object <handle-object>`.
*key* is an already open key, or one of the predefined
:ref:`HKEY_* constants <hkey-constants>`.
*sub_key* is a string that names the key this method opens or creates.
*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_ALL_ACCESS`. See
:ref:`Access Rights <access-rights>` for other allowed values.
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, a
:exc:`WindowsError` exception is raised.
.. versionadded:: 2.7
.. function:: DeleteKey(key, sub_key)
Deletes the specified key.
*key* is an already open key, or any one of the predefined
:ref:`HKEY_* constants <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, a :exc:`WindowsError` exception is raised.
.. function:: DeleteKeyEx(key, sub_key[, sam[, res]])
Deletes the specified key.
.. note::
The :func:`DeleteKeyEx` function is implemented with the RegDeleteKeyEx
Windows API function, which is specific to 64-bit versions of Windows.
See the `RegDeleteKeyEx documentation
<http://msdn.microsoft.com/en-us/library/ms724847%28VS.85%29.aspx>`__.
*key* is an already open key, or any one of the predefined
:ref:`HKEY_* constants <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.
*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_WOW64_64KEY`. See
:ref:`Access Rights <access-rights>` for other allowed values.
*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, a :exc:`WindowsError` exception is raised.
On unsupported Windows versions, :exc:`NotImplementedError` is raised.
.. versionadded:: 2.7
.. function:: DeleteValue(key, value)
Removes a named value from a registry key.
*key* is an already open key, or one of the predefined
:ref:`HKEY_* constants <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
:ref:`HKEY_* constants <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 a :exc:`WindowsError` 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
:ref:`HKEY_* constants <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 a :exc:`WindowsError` 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 (see table in docs for |
| | :meth:`SetValueEx`) |
+-------+--------------------------------------------+
.. function:: ExpandEnvironmentStrings(unicode)
Expands environment variable placeholders ``%NAME%`` in unicode strings like
:const:`REG_EXPAND_SZ`::
>>> ExpandEnvironmentStrings(u"%windir%")
u"C:\\Windows"
.. versionadded:: 2.6
.. function:: FlushKey(key)
Writes all the attributes of a key to the registry.
*key* is an already open key, or one of the predefined
:ref:`HKEY_* constants <hkey-constants>`.
It is not necessary to call :func:`FlushKey` 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:: LoadKey(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 a handle returned by :func:`ConnectRegistry` or one of the constants
:const:`HKEY_USERS` or :const:`HKEY_LOCAL_MACHINE`.
*sub_key* is a string that identifies the subkey 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 :func:`LoadKey` fails if the calling process does not have the
:const:`SE_RESTORE_PRIVILEGE` privilege. Note that privileges are different
from permissions -- see the `RegLoadKey documentation
<http://msdn.microsoft.com/en-us/library/ms724889%28v=VS.85%29.aspx>`__ for
more details.
If *key* is a handle returned by :func:`ConnectRegistry`, then the path
specified in *file_name* is relative to the remote computer.
.. function:: OpenKey(key, sub_key[, res[, sam]])
Opens the specified key, returning a :ref:`handle object <handle-object>`.
*key* is an already open key, or any one of the predefined
:ref:`HKEY_* constants <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`. See
:ref:`Access Rights <access-rights>` for other allowed values.
The result is a new handle to the specified key.
If the function fails, :exc:`WindowsError` 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
:ref:`HKEY_* constants <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, 1601. |
+-------+---------------------------------------------+
.. 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
:ref:`HKEY_* constants <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, so always use
:func:`QueryValueEx` if possible.
.. 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
:ref:`HKEY_* constants <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 (see table in docs for |
| | :meth:`SetValueEx`) |
+-------+-----------------------------------------+
.. 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
:ref:`HKEY_* constants <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`
method.
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
`Conflicts Between User Rights and Permissions documentation
<http://msdn.microsoft.com/en-us/library/ms724878%28v=VS.85%29.aspx>`__
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
:ref:`HKEY_* constants <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
:ref:`HKEY_* constants <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. See
:ref:`Value Types <value-types>` for the available types.
*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:`CreateKey` 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.
.. function:: DisableReflectionKey(key)
Disables registry reflection for 32-bit processes running on a 64-bit
operating system.
*key* is an already open key, or one of the predefined
:ref:`HKEY_* constants <hkey-constants>`.
Will generally raise :exc:`NotImplementedError` if executed on a 32-bit
operating system.
If the key is not on the reflection list, the function succeeds but has no
effect. Disabling reflection for a key does not affect reflection of any
subkeys.
.. function:: EnableReflectionKey(key)
Restores registry reflection for the specified disabled key.
*key* is an already open key, or one of the predefined
:ref:`HKEY_* constants <hkey-constants>`.
Will generally raise :exc:`NotImplementedError` if executed on a 32-bit
operating system.
Restoring reflection for a key does not affect reflection of any subkeys.
.. function:: QueryReflectionKey(key)
Determines the reflection state for the specified key.
*key* is an already open key, or one of the predefined
:ref:`HKEY_* constants <hkey-constants>`.
Returns ``True`` if reflection is disabled.
Will generally raise :exc:`NotImplementedError` if executed on a 32-bit
operating system.
.. _constants:
Constants
------------------
The following constants are defined for use in many :mod:`_winreg` functions.
.. _hkey-constants:
HKEY_* Constants
++++++++++++++++
.. data:: HKEY_CLASSES_ROOT
Registry entries subordinate to this key define types (or classes) of
documents and the properties associated with those types. Shell and
COM applications use the information stored under this key.
.. data:: HKEY_CURRENT_USER
Registry entries subordinate to this key define the preferences of
the current user. These preferences include the settings of
environment variables, data about program groups, colors, printers,
network connections, and application preferences.
.. data:: HKEY_LOCAL_MACHINE
Registry entries subordinate to this key define the physical state
of the computer, including data about the bus type, system memory,
and installed hardware and software.
.. data:: HKEY_USERS
Registry entries subordinate to this key define the default user
configuration for new users on the local computer and the user
configuration for the current user.
.. data:: HKEY_PERFORMANCE_DATA
Registry entries subordinate to this key allow you to access
performance data. The data is not actually stored in the registry;
the registry functions cause the system to collect the data from
its source.
.. data:: HKEY_CURRENT_CONFIG
Contains information about the current hardware profile of the
local computer system.
.. data:: HKEY_DYN_DATA
This key is not used in versions of Windows after 98.
.. _access-rights:
Access Rights
+++++++++++++
For more information, see `Registry Key Security and Access
<http://msdn.microsoft.com/en-us/library/ms724878%28v=VS.85%29.aspx>`__.
.. data:: KEY_ALL_ACCESS
Combines the STANDARD_RIGHTS_REQUIRED, :const:`KEY_QUERY_VALUE`,
:const:`KEY_SET_VALUE`, :const:`KEY_CREATE_SUB_KEY`,
:const:`KEY_ENUMERATE_SUB_KEYS`, :const:`KEY_NOTIFY`,
and :const:`KEY_CREATE_LINK` access rights.
.. data:: KEY_WRITE
Combines the STANDARD_RIGHTS_WRITE, :const:`KEY_SET_VALUE`, and
:const:`KEY_CREATE_SUB_KEY` access rights.
.. data:: KEY_READ
Combines the STANDARD_RIGHTS_READ, :const:`KEY_QUERY_VALUE`,
:const:`KEY_ENUMERATE_SUB_KEYS`, and :const:`KEY_NOTIFY` values.
.. data:: KEY_EXECUTE
Equivalent to :const:`KEY_READ`.
.. data:: KEY_QUERY_VALUE
Required to query the values of a registry key.
.. data:: KEY_SET_VALUE
Required to create, delete, or set a registry value.
.. data:: KEY_CREATE_SUB_KEY
Required to create a subkey of a registry key.
.. data:: KEY_ENUMERATE_SUB_KEYS
Required to enumerate the subkeys of a registry key.
.. data:: KEY_NOTIFY
Required to request change notifications for a registry key or for
subkeys of a registry key.
.. data:: KEY_CREATE_LINK
Reserved for system use.
.. _64-bit-access-rights:
64-bit Specific
***************
For more information, see `Accessing an Alternate Registry View
<http://msdn.microsoft.com/en-us/library/aa384129(v=VS.85).aspx>`__.
.. data:: KEY_WOW64_64KEY
Indicates that an application on 64-bit Windows should operate on
the 64-bit registry view.
.. data:: KEY_WOW64_32KEY
Indicates that an application on 64-bit Windows should operate on
the 32-bit registry view.
.. _value-types:
Value Types
+++++++++++
For more information, see `Registry Value Types
<http://msdn.microsoft.com/en-us/library/ms724884%28v=VS.85%29.aspx>`__.
.. data:: REG_BINARY
Binary data in any form.
.. data:: REG_DWORD
32-bit number.
.. data:: REG_DWORD_LITTLE_ENDIAN
A 32-bit number in little-endian format.
.. data:: REG_DWORD_BIG_ENDIAN
A 32-bit number in big-endian format.
.. data:: REG_EXPAND_SZ
Null-terminated string containing references to environment
variables (``%PATH%``).
.. data:: REG_LINK
A Unicode symbolic link.
.. data:: REG_MULTI_SZ
A sequence of null-terminated strings, terminated by two null characters.
(Python handles this termination automatically.)
.. data:: REG_NONE
No defined value type.
.. data:: REG_RESOURCE_LIST
A device-driver resource list.
.. data:: REG_FULL_RESOURCE_DESCRIPTOR
A hardware setting.
.. data:: REG_RESOURCE_REQUIREMENTS_LIST
A hardware resource list.
.. data:: REG_SZ
A null-terminated string.
.. _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:`~PyHKEY.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:`__nonzero__` -- 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 built-in
:func:`int` function), in which case the underlying Windows handle value is
returned. You can also use the :meth:`~PyHKEY.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.
.. method:: PyHKEY.__enter__()
PyHKEY.__exit__(\*exc_info)
The HKEY object implements :meth:`~object.__enter__` and
:meth:`~object.__exit__` and thus supports the context protocol for the
:keyword:`with` statement::
with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key:
... # work with key
will automatically close *key* when control leaves the :keyword:`with` block.
.. versionadded:: 2.6

200
Doc/library/abc.rst Normal file
View File

@@ -0,0 +1,200 @@
:mod:`abc` --- Abstract Base Classes
====================================
.. module:: abc
:synopsis: Abstract base classes according to PEP 3119.
.. moduleauthor:: Guido van Rossum
.. sectionauthor:: Georg Brandl
.. much of the content adapted from docstrings
.. versionadded:: 2.6
**Source code:** :source:`Lib/abc.py`
--------------
This module provides the infrastructure for defining :term:`abstract base
classes <abstract base class>` (ABCs) in Python, as outlined in :pep:`3119`; see the PEP for why this
was added to Python. (See also :pep:`3141` and the :mod:`numbers` module
regarding a type hierarchy for numbers based on ABCs.)
The :mod:`collections` module has some concrete classes that derive from
ABCs; these can, of course, be further derived. In addition, the
:mod:`collections` module has some ABCs that can be used to test whether
a class or instance provides a particular interface, for example, if it is
hashable or if it is a mapping.
This module provides the following class:
.. class:: ABCMeta
Metaclass for defining Abstract Base Classes (ABCs).
Use this metaclass to create an ABC. An ABC can be subclassed directly, and
then acts as a mix-in class. You can also register unrelated concrete
classes (even built-in classes) and unrelated ABCs as "virtual subclasses" --
these and their descendants will be considered subclasses of the registering
ABC by the built-in :func:`issubclass` function, but the registering ABC
won't show up in their MRO (Method Resolution Order) nor will method
implementations defined by the registering ABC be callable (not even via
:func:`super`). [#]_
Classes created with a metaclass of :class:`ABCMeta` have the following method:
.. method:: register(subclass)
Register *subclass* as a "virtual subclass" of this ABC. For
example::
from abc import ABCMeta
class MyABC:
__metaclass__ = ABCMeta
MyABC.register(tuple)
assert issubclass(tuple, MyABC)
assert isinstance((), MyABC)
You can also override this method in an abstract base class:
.. method:: __subclasshook__(subclass)
(Must be defined as a class method.)
Check whether *subclass* is considered a subclass of this ABC. This means
that you can customize the behavior of ``issubclass`` further without the
need to call :meth:`register` on every class you want to consider a
subclass of the ABC. (This class method is called from the
:meth:`__subclasscheck__` method of the ABC.)
This method should return ``True``, ``False`` or ``NotImplemented``. If
it returns ``True``, the *subclass* is considered a subclass of this ABC.
If it returns ``False``, the *subclass* is not considered a subclass of
this ABC, even if it would normally be one. If it returns
``NotImplemented``, the subclass check is continued with the usual
mechanism.
.. XXX explain the "usual mechanism"
For a demonstration of these concepts, look at this example ABC definition::
class Foo(object):
def __getitem__(self, index):
...
def __len__(self):
...
def get_iterator(self):
return iter(self)
class MyIterable:
__metaclass__ = ABCMeta
@abstractmethod
def __iter__(self):
while False:
yield None
def get_iterator(self):
return self.__iter__()
@classmethod
def __subclasshook__(cls, C):
if cls is MyIterable:
if any("__iter__" in B.__dict__ for B in C.__mro__):
return True
return NotImplemented
MyIterable.register(Foo)
The ABC ``MyIterable`` defines the standard iterable method,
:meth:`~iterator.__iter__`, as an abstract method. The implementation given
here can still be called from subclasses. The :meth:`get_iterator` method
is also part of the ``MyIterable`` abstract base class, but it does not have
to be overridden in non-abstract derived classes.
The :meth:`__subclasshook__` class method defined here says that any class
that has an :meth:`~iterator.__iter__` method in its
:attr:`~object.__dict__` (or in that of one of its base classes, accessed
via the :attr:`~class.__mro__` list) is considered a ``MyIterable`` too.
Finally, the last line makes ``Foo`` a virtual subclass of ``MyIterable``,
even though it does not define an :meth:`~iterator.__iter__` method (it uses
the old-style iterable protocol, defined in terms of :meth:`__len__` and
:meth:`__getitem__`). Note that this will not make ``get_iterator``
available as a method of ``Foo``, so it is provided separately.
It also provides the following decorators:
.. function:: abstractmethod(function)
A decorator indicating abstract methods.
Using this decorator requires that the class's metaclass is :class:`ABCMeta` or
is derived from it.
A class that has a metaclass derived from :class:`ABCMeta`
cannot be instantiated unless all of its abstract methods and
properties are overridden.
The abstract methods can be called using any of the normal 'super' call
mechanisms.
Dynamically adding abstract methods to a class, or attempting to modify the
abstraction status of a method or class once it is created, are not
supported. The :func:`abstractmethod` only affects subclasses derived using
regular inheritance; "virtual subclasses" registered with the ABC's
:meth:`register` method are not affected.
Usage::
class C:
__metaclass__ = ABCMeta
@abstractmethod
def my_abstract_method(self, ...):
...
.. note::
Unlike Java abstract methods, these abstract
methods may have an implementation. This implementation can be
called via the :func:`super` mechanism from the class that
overrides it. This could be useful as an end-point for a
super-call in a framework that uses cooperative
multiple-inheritance.
.. function:: abstractproperty([fget[, fset[, fdel[, doc]]]])
A subclass of the built-in :func:`property`, indicating an abstract property.
Using this function requires that the class's metaclass is :class:`ABCMeta` or
is derived from it.
A class that has a metaclass derived from :class:`ABCMeta` cannot be
instantiated unless all of its abstract methods and properties are overridden.
The abstract properties can be called using any of the normal
'super' call mechanisms.
Usage::
class C:
__metaclass__ = ABCMeta
@abstractproperty
def my_abstract_property(self):
...
This defines a read-only property; you can also define a read-write abstract
property using the 'long' form of property declaration::
class C:
__metaclass__ = ABCMeta
def getx(self): ...
def setx(self, value): ...
x = abstractproperty(getx, setx)
.. rubric:: Footnotes
.. [#] C++ programmers should note that Python's virtual base class
concept is not the same as C++'s.

92
Doc/library/aepack.rst Normal file
View File

@@ -0,0 +1,92 @@
:mod:`aepack` --- Conversion between Python variables and AppleEvent data containers
====================================================================================
.. module:: aepack
:platform: Mac
:synopsis: Conversion between Python variables and AppleEvent data containers.
:deprecated:
.. sectionauthor:: Vincent Marchetti <vincem@en.com>
.. moduleauthor:: Jack Jansen
The :mod:`aepack` module defines functions for converting (packing) Python
variables to AppleEvent descriptors and back (unpacking). Within Python the
AppleEvent descriptor is handled by Python objects of built-in type
:class:`AEDesc`, defined in module :mod:`Carbon.AE`.
.. note::
This module has been removed in Python 3.x.
The :mod:`aepack` module defines the following functions:
.. function:: pack(x[, forcetype])
Returns an :class:`AEDesc` object containing a conversion of Python value x. If
*forcetype* is provided it specifies the descriptor type of the result.
Otherwise, a default mapping of Python types to Apple Event descriptor types is
used, as follows:
+-----------------+-----------------------------------+
| Python type | descriptor type |
+=================+===================================+
| :class:`FSSpec` | typeFSS |
+-----------------+-----------------------------------+
| :class:`FSRef` | typeFSRef |
+-----------------+-----------------------------------+
| :class:`Alias` | typeAlias |
+-----------------+-----------------------------------+
| integer | typeLong (32 bit integer) |
+-----------------+-----------------------------------+
| float | typeFloat (64 bit floating point) |
+-----------------+-----------------------------------+
| string | typeText |
+-----------------+-----------------------------------+
| unicode | typeUnicodeText |
+-----------------+-----------------------------------+
| list | typeAEList |
+-----------------+-----------------------------------+
| dictionary | typeAERecord |
+-----------------+-----------------------------------+
| instance | *see below* |
+-----------------+-----------------------------------+
If *x* is a Python instance then this function attempts to call an
:meth:`__aepack__` method. This method should return an :class:`AEDesc` object.
If the conversion *x* is not defined above, this function returns the Python
string representation of a value (the repr() function) encoded as a text
descriptor.
.. function:: unpack(x[, formodulename])
*x* must be an object of type :class:`AEDesc`. This function returns a Python
object representation of the data in the Apple Event descriptor *x*. Simple
AppleEvent data types (integer, text, float) are returned as their obvious
Python counterparts. Apple Event lists are returned as Python lists, and the
list elements are recursively unpacked. Object references (ex. ``line 3 of
document 1``) are returned as instances of :class:`aetypes.ObjectSpecifier`,
unless ``formodulename`` is specified. AppleEvent descriptors with descriptor
type typeFSS are returned as :class:`FSSpec` objects. AppleEvent record
descriptors are returned as Python dictionaries, with 4-character string keys
and elements recursively unpacked.
The optional ``formodulename`` argument is used by the stub packages generated
by :mod:`gensuitemodule`, and ensures that the OSA classes for object specifiers
are looked up in the correct module. This ensures that if, say, the Finder
returns an object specifier for a window you get an instance of
``Finder.Window`` and not a generic ``aetypes.Window``. The former knows about
all the properties and elements a window has in the Finder, while the latter
knows no such things.
.. seealso::
Module :mod:`Carbon.AE`
Built-in access to Apple Event Manager routines.
Module :mod:`aetypes`
Python definitions of codes for Apple Event descriptor types.

90
Doc/library/aetools.rst Normal file
View File

@@ -0,0 +1,90 @@
:mod:`aetools` --- OSA client support
=====================================
.. module:: aetools
:platform: Mac
:synopsis: Basic support for sending Apple Events
:deprecated:
.. sectionauthor:: Jack Jansen <Jack.Jansen@cwi.nl>
.. moduleauthor:: Jack Jansen
The :mod:`aetools` module contains the basic functionality on which Python
AppleScript client support is built. It also imports and re-exports the core
functionality of the :mod:`aetypes` and :mod:`aepack` modules. The stub packages
generated by :mod:`gensuitemodule` import the relevant portions of
:mod:`aetools`, so usually you do not need to import it yourself. The exception
to this is when you cannot use a generated suite package and need lower-level
access to scripting.
The :mod:`aetools` module itself uses the AppleEvent support provided by the
:mod:`Carbon.AE` module. This has one drawback: you need access to the window
manager, see section :ref:`osx-gui-scripts` for details. This restriction may be
lifted in future releases.
.. note::
This module has been removed in Python 3.x.
The :mod:`aetools` module defines the following functions:
.. function:: packevent(ae, parameters, attributes)
Stores parameters and attributes in a pre-created ``Carbon.AE.AEDesc`` object.
``parameters`` and ``attributes`` are dictionaries mapping 4-character OSA
parameter keys to Python objects. The objects are packed using
``aepack.pack()``.
.. function:: unpackevent(ae[, formodulename])
Recursively unpacks a ``Carbon.AE.AEDesc`` event to Python objects. The function
returns the parameter dictionary and the attribute dictionary. The
``formodulename`` argument is used by generated stub packages to control where
AppleScript classes are looked up.
.. function:: keysubst(arguments, keydict)
Converts a Python keyword argument dictionary ``arguments`` to the format
required by ``packevent`` by replacing the keys, which are Python identifiers,
by the four-character OSA keys according to the mapping specified in
``keydict``. Used by the generated suite packages.
.. function:: enumsubst(arguments, key, edict)
If the ``arguments`` dictionary contains an entry for ``key`` convert the value
for that entry according to dictionary ``edict``. This converts human-readable
Python enumeration names to the OSA 4-character codes. Used by the generated
suite packages.
The :mod:`aetools` module defines the following class:
.. class:: TalkTo([signature=None, start=0, timeout=0])
Base class for the proxy used to talk to an application. ``signature`` overrides
the class attribute ``_signature`` (which is usually set by subclasses) and is
the 4-char creator code defining the application to talk to. ``start`` can be
set to true to enable running the application on class instantiation.
``timeout`` can be specified to change the default timeout used while waiting
for an AppleEvent reply.
.. method:: TalkTo._start()
Test whether the application is running, and attempt to start it if not.
.. method:: TalkTo.send(code, subcode[, parameters, attributes])
Create the AppleEvent ``Carbon.AE.AEDesc`` for the verb with the OSA designation
``code, subcode`` (which are the usual 4-character strings), pack the
``parameters`` and ``attributes`` into it, send it to the target application,
wait for the reply, unpack the reply with ``unpackevent`` and return the reply
appleevent, the unpacked return values as a dictionary and the return
attributes.

155
Doc/library/aetypes.rst Normal file
View File

@@ -0,0 +1,155 @@
:mod:`aetypes` --- AppleEvent objects
=====================================
.. module:: aetypes
:platform: Mac
:synopsis: Python representation of the Apple Event Object Model.
:deprecated:
.. sectionauthor:: Vincent Marchetti <vincem@en.com>
.. moduleauthor:: Jack Jansen
The :mod:`aetypes` defines classes used to represent Apple Event data
descriptors and Apple Event object specifiers.
Apple Event data is contained in descriptors, and these descriptors are typed.
For many descriptors the Python representation is simply the corresponding
Python type: ``typeText`` in OSA is a Python string, ``typeFloat`` is a float,
etc. For OSA types that have no direct Python counterpart this module declares
classes. Packing and unpacking instances of these classes is handled
automatically by :mod:`aepack`.
An object specifier is essentially an address of an object implemented in an
Apple Event server. An Apple Event specifier is used as the direct object for an
Apple Event or as the argument of an optional parameter. The :mod:`aetypes`
module contains the base classes for OSA classes and properties, which are used
by the packages generated by :mod:`gensuitemodule` to populate the classes and
properties in a given suite.
For reasons of backward compatibility, and for cases where you need to script an
application for which you have not generated the stub package this module also
contains object specifiers for a number of common OSA classes such as
``Document``, ``Window``, ``Character``, etc.
.. note::
This module has been removed in Python 3.x.
The :mod:`AEObjects` module defines the following classes to represent Apple
Event descriptor data:
.. class:: Unknown(type, data)
The representation of OSA descriptor data for which the :mod:`aepack` and
:mod:`aetypes` modules have no support, i.e. anything that is not represented by
the other classes here and that is not equivalent to a simple Python value.
.. class:: Enum(enum)
An enumeration value with the given 4-character string value.
.. class:: InsertionLoc(of, pos)
Position ``pos`` in object ``of``.
.. class:: Boolean(bool)
A boolean.
.. class:: StyledText(style, text)
Text with style information (font, face, etc) included.
.. class:: AEText(script, style, text)
Text with script system and style information included.
.. class:: IntlText(script, language, text)
Text with script system and language information included.
.. class:: IntlWritingCode(script, language)
Script system and language information.
.. class:: QDPoint(v, h)
A quickdraw point.
.. class:: QDRectangle(v0, h0, v1, h1)
A quickdraw rectangle.
.. class:: RGBColor(r, g, b)
A color.
.. class:: Type(type)
An OSA type value with the given 4-character name.
.. class:: Keyword(name)
An OSA keyword with the given 4-character name.
.. class:: Range(start, stop)
A range.
.. class:: Ordinal(abso)
Non-numeric absolute positions, such as ``"firs"``, first, or ``"midd"``,
middle.
.. class:: Logical(logc, term)
The logical expression of applying operator ``logc`` to ``term``.
.. class:: Comparison(obj1, relo, obj2)
The comparison ``relo`` of ``obj1`` to ``obj2``.
The following classes are used as base classes by the generated stub packages to
represent AppleScript classes and properties in Python:
.. class:: ComponentItem(which[, fr])
Abstract baseclass for an OSA class. The subclass should set the class attribute
``want`` to the 4-character OSA class code. Instances of subclasses of this
class are equivalent to AppleScript Object Specifiers. Upon instantiation you
should pass a selector in ``which``, and optionally a parent object in ``fr``.
.. class:: NProperty(fr)
Abstract baseclass for an OSA property. The subclass should set the class
attributes ``want`` and ``which`` to designate which property we are talking
about. Instances of subclasses of this class are Object Specifiers.
.. class:: ObjectSpecifier(want, form, seld[, fr])
Base class of ``ComponentItem`` and ``NProperty``, a general OSA Object
Specifier. See the Apple Open Scripting Architecture documentation for the
parameters. Note that this class is not abstract.

230
Doc/library/aifc.rst Normal file
View File

@@ -0,0 +1,230 @@
: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
**Source code:** :source:`Lib/aifc.py`
--------------
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.
.. note::
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.

214
Doc/library/al.rst Normal file
View File

@@ -0,0 +1,214 @@
:mod:`al` --- Audio functions on the SGI
========================================
.. module:: al
:platform: IRIX
:synopsis: Audio functions on the SGI.
:deprecated:
.. deprecated:: 2.6
The :mod:`al` module has been removed in Python 3.
This module provides access to the audio facilities of the SGI Indy and Indigo
workstations. See section 3A of the IRIX man pages for details. You'll need to
read those man pages to understand what these functions do! Some of the
functions are not available in IRIX releases before 4.0.5. Again, see the
manual to check whether a specific function is available on your platform.
All functions and methods defined in this module are equivalent to the C
functions with ``AL`` prefixed to their name.
.. index:: module: AL
Symbolic constants from the C header file ``<audio.h>`` are defined in the
standard module :mod:`AL`, see below.
.. warning::
The current version of the audio library may dump core when bad argument values
are passed rather than returning an error status. Unfortunately, since the
precise circumstances under which this may happen are undocumented and hard to
check, the Python interface can provide no protection against this kind of
problems. (One example is specifying an excessive queue size --- there is no
documented upper limit.)
The module defines the following functions:
.. function:: openport(name, direction[, config])
The name and direction arguments are strings. The optional *config* argument is
a configuration object as returned by :func:`newconfig`. The return value is an
:dfn:`audio port object`; methods of audio port objects are described below.
.. function:: newconfig()
The return value is a new :dfn:`audio configuration object`; methods of audio
configuration objects are described below.
.. function:: queryparams(device)
The device argument is an integer. The return value is a list of integers
containing the data returned by :c:func:`ALqueryparams`.
.. function:: getparams(device, list)
The *device* argument is an integer. The list argument is a list such as
returned by :func:`queryparams`; it is modified in place (!).
.. function:: setparams(device, list)
The *device* argument is an integer. The *list* argument is a list such as
returned by :func:`queryparams`.
.. _al-config-objects:
Configuration Objects
---------------------
Configuration objects returned by :func:`newconfig` have the following methods:
.. method:: audio configuration.getqueuesize()
Return the queue size.
.. method:: audio configuration.setqueuesize(size)
Set the queue size.
.. method:: audio configuration.getwidth()
Get the sample width.
.. method:: audio configuration.setwidth(width)
Set the sample width.
.. method:: audio configuration.getchannels()
Get the channel count.
.. method:: audio configuration.setchannels(nchannels)
Set the channel count.
.. method:: audio configuration.getsampfmt()
Get the sample format.
.. method:: audio configuration.setsampfmt(sampfmt)
Set the sample format.
.. method:: audio configuration.getfloatmax()
Get the maximum value for floating sample formats.
.. method:: audio configuration.setfloatmax(floatmax)
Set the maximum value for floating sample formats.
.. _al-port-objects:
Port Objects
------------
Port objects, as returned by :func:`openport`, have the following methods:
.. method:: audio port.closeport()
Close the port.
.. method:: audio port.getfd()
Return the file descriptor as an int.
.. method:: audio port.getfilled()
Return the number of filled samples.
.. method:: audio port.getfillable()
Return the number of fillable samples.
.. method:: audio port.readsamps(nsamples)
Read a number of samples from the queue, blocking if necessary. Return the data
as a string containing the raw data, (e.g., 2 bytes per sample in big-endian
byte order (high byte, low byte) if you have set the sample width to 2 bytes).
.. method:: audio port.writesamps(samples)
Write samples into the queue, blocking if necessary. The samples are encoded as
described for the :meth:`readsamps` return value.
.. method:: audio port.getfillpoint()
Return the 'fill point'.
.. method:: audio port.setfillpoint(fillpoint)
Set the 'fill point'.
.. method:: audio port.getconfig()
Return a configuration object containing the current configuration of the port.
.. method:: audio port.setconfig(config)
Set the configuration from the argument, a configuration object.
.. method:: audio port.getstatus(list)
Get status information on last error.
:mod:`AL` --- Constants used with the :mod:`al` module
======================================================
.. module:: AL
:platform: IRIX
:synopsis: Constants used with the al module.
:deprecated:
.. deprecated:: 2.6
The :mod:`AL` module has been removed in Python 3.
This module defines symbolic constants needed to use the built-in module
:mod:`al` (see above); they are equivalent to those defined in the C header file
``<audio.h>`` except that the name prefix ``AL_`` is omitted. Read the module
source for a complete list of the defined names. Suggested use::
import al
from AL import *

31
Doc/library/allos.rst Normal file
View File

@@ -0,0 +1,31 @@
.. _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
io.rst
time.rst
argparse.rst
optparse.rst
getopt.rst
logging.rst
logging.config.rst
logging.handlers.rst
getpass.rst
curses.rst
curses.ascii.rst
curses.panel.rst
platform.rst
errno.rst
ctypes.rst

122
Doc/library/anydbm.rst Normal file
View File

@@ -0,0 +1,122 @@
:mod:`anydbm` --- Generic access to DBM-style databases
=======================================================
.. module:: anydbm
:synopsis: Generic interface to DBM-style database modules.
.. note::
The :mod:`anydbm` module has been renamed to :mod:`dbm` in Python 3. The
:term:`2to3` tool will automatically adapt imports when converting your
sources to Python 3.
.. 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 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 |
+---------+-------------------------------------------+
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 also named :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()
In addition to the dictionary-like methods, ``anydbm`` objects
provide the following method:
.. function:: close()
Close the ``anydbm`` database.
.. 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.

19
Doc/library/archiving.rst Normal file
View File

@@ -0,0 +1,19 @@
.. _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.
See also :ref:`archiving-operations` provided by the :mod:`shutil` module.
.. toctree::
zlib.rst
gzip.rst
bz2.rst
zipfile.rst
tarfile.rst

1975
Doc/library/argparse.rst Normal file
View File

File diff suppressed because it is too large Load Diff

274
Doc/library/array.rst Normal file
View File

@@ -0,0 +1,274 @@
:mod:`array` --- Efficient arrays of numeric values
===================================================
.. module:: array
:synopsis: Space efficient arrays of uniformly typed numeric values.
.. index:: single: arrays
This module defines an object type which can compactly 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 (see note) |
+-----------+----------------+-------------------+-----------------------+
| ``'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 |
+-----------+----------------+-------------------+-----------------------+
.. note::
The ``'u'`` typecode corresponds to Python's unicode character. On narrow
Unicode builds this is 2-bytes, on wide builds this is 4-bytes.
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:
.. class:: array(typecode[, initializer])
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 :class:`~array.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
:c:func:`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 :ref:`bufferobjects`.
.. 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(unicodestring.encode(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 :func:`eval`, so long as the
:class:`~array.array` class has been imported using ``from array import array``.
Examples::
array('l')
array('c', 'hello world')
array('u', u'hello \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 Documentation <https://docs.scipy.org/doc/>`_
The Numeric Python extension (NumPy) defines another array type; see
http://www.numpy.org/ for further information about Numerical Python.

275
Doc/library/ast.rst Normal file
View File

@@ -0,0 +1,275 @@
:mod:`ast` --- Abstract Syntax Trees
====================================
.. module:: ast
:synopsis: Abstract Syntax Tree classes and manipulation.
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
.. sectionauthor:: Georg Brandl <georg@python.org>
.. versionadded:: 2.5
The low-level ``_ast`` module containing only the node classes.
.. versionadded:: 2.6
The high-level ``ast`` module containing all helpers.
**Source code:** :source:`Lib/ast.py`
--------------
The :mod:`ast` module helps Python applications to process trees of the Python
abstract syntax grammar. 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 :data:`ast.PyCF_ONLY_AST` as
a flag to the :func:`compile` built-in function, or using the :func:`parse`
helper provided in this module. The result will be a tree of objects whose
classes all inherit from :class:`ast.AST`. An abstract syntax tree can be
compiled into a Python code object using the built-in :func:`compile` function.
Node classes
------------
.. class:: AST
This is the base of all AST node classes. The actual node classes are
derived from the :file:`Parser/Python.asdl` file, which is reproduced
:ref:`below <abstract-grammar>`. They are defined in the :mod:`_ast` C
module and re-exported in :mod:`ast`.
There is one class defined for each left-hand side symbol in the abstract
grammar (for example, :class:`ast.stmt` or :class:`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,
:class:`ast.BinOp` inherits from :class:`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.
.. attribute:: _fields
Each concrete class has an attribute :attr:`_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, :class:`ast.BinOp`
instances have an attribute :attr:`left` of type :class:`ast.expr`.
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. All possible attributes must be present and have valid
values when compiling an AST with :func:`compile`.
.. attribute:: lineno
col_offset
Instances of :class:`ast.expr` and :class:`ast.stmt` subclasses have
:attr:`lineno` and :attr:`col_offset` attributes. The :attr:`lineno` is
the line number of source text (1-indexed so the first line is line 1) and
the :attr:`col_offset` is the UTF-8 byte offset of the first token that
generated the node. The UTF-8 offset is recorded because the parser uses
UTF-8 internally.
The constructor of a class :class:`ast.T` parses its arguments as follows:
* If there are positional arguments, there must be as many as there are items
in :attr:`T._fields`; they will be assigned as attributes of these names.
* If there are keyword arguments, they will set the attributes of the same
names to the given values.
For example, to create and populate an :class:`ast.UnaryOp` node, you could
use ::
node = ast.UnaryOp()
node.op = ast.USub()
node.operand = ast.Num()
node.operand.n = 5
node.operand.lineno = 0
node.operand.col_offset = 0
node.lineno = 0
node.col_offset = 0
or the more compact ::
node = ast.UnaryOp(ast.USub(), ast.Num(5, lineno=0, col_offset=0),
lineno=0, col_offset=0)
.. versionadded:: 2.6
The constructor as explained above was added. In Python 2.5 nodes had
to be created by calling the class constructor without arguments and
setting the attributes afterwards.
.. _abstract-grammar:
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:
.. literalinclude:: ../../Parser/Python.asdl
:language: none
:mod:`ast` Helpers
------------------
.. versionadded:: 2.6
Apart from the node classes, :mod:`ast` module defines these utility functions
and classes for traversing abstract syntax trees:
.. function:: parse(source, filename='<unknown>', mode='exec')
Parse the source into an AST node. Equivalent to ``compile(source,
filename, mode, ast.PyCF_ONLY_AST)``.
.. warning::
It is possible to crash the Python interpreter with a
sufficiently large/complex string due to stack depth limitations
in Python's AST compiler.
.. function:: literal_eval(node_or_string)
Safely evaluate an expression node or a Unicode or *Latin-1* encoded string
containing a Python literal or container display. The string or node
provided may only consist of the following Python literal structures:
strings, numbers, tuples, lists, dicts, booleans, and ``None``.
This can be used for safely evaluating strings containing Python values from
untrusted sources without the need to parse the values oneself. It is not
capable of evaluating arbitrarily complex expressions, for example involving
operators or indexing.
.. warning::
It is possible to crash the Python interpreter with a
sufficiently large/complex string due to stack depth limitations
in Python's AST compiler.
.. function:: get_docstring(node, clean=True)
Return the docstring of the given *node* (which must be a
:class:`FunctionDef`, :class:`ClassDef` or :class:`Module` node), or ``None``
if it has no docstring. If *clean* is true, clean up the docstring's
indentation with :func:`inspect.cleandoc`.
.. function:: fix_missing_locations(node)
When you compile a node tree with :func:`compile`, the compiler expects
:attr:`lineno` and :attr:`col_offset` attributes for every node that supports
them. This is rather tedious to fill in for generated nodes, so this helper
adds these attributes recursively where not already set, by setting them to
the values of the parent node. It works recursively starting at *node*.
.. function:: increment_lineno(node, n=1)
Increment the line number of each node in the tree starting at *node* by *n*.
This is useful to "move code" to a different location in a file.
.. function:: copy_location(new_node, old_node)
Copy source location (:attr:`lineno` and :attr:`col_offset`) from *old_node*
to *new_node* if possible, and return *new_node*.
.. function:: iter_fields(node)
Yield a tuple of ``(fieldname, value)`` for each field in ``node._fields``
that is present on *node*.
.. function:: iter_child_nodes(node)
Yield all direct child nodes of *node*, that is, all fields that are nodes
and all items of fields that are lists of nodes.
.. function:: walk(node)
Recursively yield all descendant nodes in the tree starting at *node*
(including *node* itself), in no specified order. This is useful if you only
want to modify nodes in place and don't care about the context.
.. class:: NodeVisitor()
A node visitor base class that walks the abstract syntax tree and calls a
visitor function for every node found. This function may return a value
which is forwarded by the :meth:`visit` method.
This class is meant to be subclassed, with the subclass adding visitor
methods.
.. method:: visit(node)
Visit a node. The default implementation calls the method called
:samp:`self.visit_{classname}` where *classname* is the name of the node
class, or :meth:`generic_visit` if that method doesn't exist.
.. method:: generic_visit(node)
This visitor calls :meth:`visit` on all children of the node.
Note that child nodes of nodes that have a custom visitor method won't be
visited unless the visitor calls :meth:`generic_visit` or visits them
itself.
Don't use the :class:`NodeVisitor` if you want to apply changes to nodes
during traversal. For this a special visitor exists
(:class:`NodeTransformer`) that allows modifications.
.. class:: NodeTransformer()
A :class:`NodeVisitor` subclass that walks the abstract syntax tree and
allows modification of nodes.
The :class:`NodeTransformer` will walk the AST and use the return value of
the visitor methods to replace or remove the old node. If the return value
of the visitor method is ``None``, the node will be removed from its
location, otherwise it is replaced with the return value. The return value
may be the original node in which case no replacement takes place.
Here is an example transformer that rewrites all occurrences of name lookups
(``foo``) to ``data['foo']``::
class RewriteName(NodeTransformer):
def visit_Name(self, node):
return copy_location(Subscript(
value=Name(id='data', ctx=Load()),
slice=Index(value=Str(s=node.id)),
ctx=node.ctx
), node)
Keep in mind that if the node you're operating on has child nodes you must
either transform the child nodes yourself or call the :meth:`generic_visit`
method for the node first.
For nodes that were part of a collection of statements (that applies to all
statement nodes), the visitor may also return a list of nodes rather than
just a single node.
Usually you use the transformer like this::
node = YourTransformer().visit(node)
.. function:: dump(node, annotate_fields=True, include_attributes=False)
Return a formatted dump of the tree in *node*. This is mainly useful for
debugging purposes. The returned string will show the names and the values
for fields. This makes the code impossible to evaluate, so if evaluation is
wanted *annotate_fields* must be set to ``False``. Attributes such as line
numbers and column offsets are not dumped by default. If this is wanted,
*include_attributes* can be set to ``True``.

235
Doc/library/asynchat.rst Normal file
View File

@@ -0,0 +1,235 @@
: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>
**Source code:** :source:`Lib/asynchat.py`
--------------
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
:c:func:`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.
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``).
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.push(data)
Pushes data on to the channel's 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.set_terminator(term)
Sets the terminating condition to be recognized 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.
asynchat - Auxiliary Classes
------------------------------------------
.. class:: fifo([list=None])
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:: is_empty()
Returns ``True`` if and only if the fifo is empty.
.. method:: first()
Returns the least-recently :meth:`push`\ ed item from the fifo.
.. method:: push(data)
Adds the given data (which may be a string or a producer object) to the
producer fifo.
.. method:: pop()
If the fifo is not empty, returns ``True, first()``, deleting the popped
item. Returns ``False, None`` for an empty fifo.
.. _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, sock, addr, sessions, log):
asynchat.async_chat.__init__(self, sock=sock)
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()

332
Doc/library/asyncore.rst Normal file
View File

@@ -0,0 +1,332 @@
: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>
.. heavily adapted from original documentation by Sam Rushing
**Source code:** :source:`Lib/asyncore.py`
--------------
This module provides the basic infrastructure for writing asynchronous socket
service clients and servers.
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 :c:func:`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.select` or :func:`~select.poll`
call, measured in seconds; the default is 30 seconds. The *use_poll*
parameter, if true, indicates that :func:`~select.poll` should be used in
preference to :func:`~select.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.
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 read or 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 :c:func:`select`\ ed or
:c:func:`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:: handle_read()
Called when the asynchronous loop detects that a :meth:`read` call on the
channel's socket will succeed.
.. method:: 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:: 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:: 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:: handle_close()
Called when the socket is closed.
.. method:: handle_error()
Called when an exception is raised and not otherwise handled. The default
version prints a condensed traceback.
.. method:: 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:: 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:: 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:: 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:: 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:: send(data)
Send *data* to the remote end-point of the socket.
.. method:: 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.
Note that :meth:`recv` may raise :exc:`socket.error` with
:data:`~errno.EAGAIN` or :data:`~errno.EWOULDBLOCK`, even though
:func:`select.select` or :func:`select.poll` has reported the socket
ready for reading.
.. method:: 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:: bind(address)
Bind the socket to *address*. The socket must not already be bound. (The
format of *address* depends on the address family --- refer to the
:mod:`socket` documentation for more information.) 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:: accept()
Accept a connection. The socket must be bound to an address and listening
for connections. The return value can be either ``None`` or 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.
When ``None`` is returned it means the connection didn't take place, in
which case the server should just ignore this event and keep listening
for further incoming connections.
.. method:: 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.
.. class:: dispatcher_with_send()
A :class:`dispatcher` subclass which adds simple buffered output capability,
useful for simple clients. For more sophisticated usage use
:class:`asynchat.async_chat`.
.. class:: file_dispatcher()
A file_dispatcher takes a file descriptor or file object along with an
optional map argument and wraps it for use with the :c:func:`poll` or
:c:func:`loop` functions. If provided a file object or anything with a
:c:func:`fileno` method, that method will be called and passed to the
:class:`file_wrapper` constructor. Availability: UNIX.
.. class:: file_wrapper()
A file_wrapper takes an integer file descriptor and calls :func:`os.dup` to
duplicate the handle so that the original handle may be closed independently
of the file_wrapper. This class implements sufficient methods to emulate a
socket for use by the :class:`file_dispatcher` class. Availability: UNIX.
.. _asyncore-example-1:
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 HTTPClient(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:]
client = HTTPClient('www.python.org', '/')
asyncore.loop()
.. _asyncore-example-2:
asyncore Example basic echo server
----------------------------------
Here is a basic echo server that uses the :class:`dispatcher` class to accept
connections and dispatches the incoming connections to a handler::
import asyncore
import socket
class EchoHandler(asyncore.dispatcher_with_send):
def handle_read(self):
data = self.recv(8192)
if data:
self.send(data)
class EchoServer(asyncore.dispatcher):
def __init__(self, host, port):
asyncore.dispatcher.__init__(self)
self.create_socket(socket.AF_INET, socket.SOCK_STREAM)
self.set_reuse_addr()
self.bind((host, port))
self.listen(5)
def handle_accept(self):
pair = self.accept()
if pair is not None:
sock, addr = pair
print 'Incoming connection from %s' % repr(addr)
handler = EchoHandler(sock)
server = EchoServer('localhost', 8080)
asyncore.loop()

114
Doc/library/atexit.rst Normal file
View File

@@ -0,0 +1,114 @@
:mod:`atexit` --- Exit handlers
===============================
.. module:: atexit
:synopsis: Register and execute cleanup functions.
.. moduleauthor:: Skip Montanaro <skip@pobox.com>
.. sectionauthor:: Skip Montanaro <skip@pobox.com>
.. versionadded:: 2.0
**Source code:** :source:`Lib/atexit.py`
--------------
The :mod:`atexit` module defines a single function to register cleanup
functions. Functions thus registered are automatically executed upon normal
interpreter termination. :mod:`atexit` runs these functions in the *reverse*
order in which they were registered; if you register ``A``, ``B``, and ``C``,
at interpreter termination time they will be run in the order ``C``, ``B``,
``A``.
**Note:** The functions registered via this module are not called when the
program is killed by a signal not handled by Python, when a Python fatal
internal error is detected, or when :func:`os._exit` is called.
.. index:: single: exitfunc (in sys)
This is an alternate interface to the functionality provided by the
:func:`sys.exitfunc` variable.
Note: This module is unlikely to work correctly when used with other code that
sets ``sys.exitfunc``. In particular, other core Python modules are free to use
:mod:`atexit` without the programmer's knowledge. Authors who use
``sys.exitfunc`` should convert their code to use :mod:`atexit` instead. The
simplest way to convert code that sets ``sys.exitfunc`` is to import
:mod:`atexit` and register the function that had been bound to ``sys.exitfunc``.
.. function:: register(func[, *args[, **kwargs]])
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`. It is possible to register the same function and arguments
more than once.
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.
.. 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("counter").read())
except IOError:
_count = 0
def incrcounter(n):
global _count
_count = _count + n
def savecounter():
open("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 :term:`decorator`::
import atexit
@atexit.register
def goodbye():
print "You are now leaving the Python sector."
This only works with functions that can be called without arguments.

274
Doc/library/audioop.rst Normal file
View File

@@ -0,0 +1,274 @@
: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. Samples are truncated in case of overflow.
.. 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. Samples wrap around in case of overflow.
.. 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.
.. note::
In some audio formats, such as .WAV files, 16 and 32 bit samples are
signed, but 8 bit samples are unsigned. So when converting to 8 bit wide
samples for these formats, you need to also add 128 to the result::
new_frames = audioop.lin2lin(frames, old_width, 1)
new_frames = audioop.bias(new_frames, 1, 128)
The same, in reverse, has to be applied when converting from 8 to 16 or 32
bit width samples.
.. 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:: 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:: minmax(fragment, width)
Return a tuple consisting of the minimum and maximum values of all samples 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*. Samples are truncated in case of overflow.
.. 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. ``sqrt(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(lsample, width, lfactor)
rsample = audioop.mul(rsample, 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
:class:`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)

35
Doc/library/autogil.rst Normal file
View File

@@ -0,0 +1,35 @@
:mod:`autoGIL` --- Global Interpreter Lock handling in event loops
==================================================================
.. module:: autoGIL
:platform: Mac
:synopsis: Global Interpreter Lock handling in event loops.
:deprecated:
.. moduleauthor:: Just van Rossum <just@letterror.com>
The :mod:`autoGIL` module provides a function :func:`installAutoGIL` that
automatically locks and unlocks Python's :term:`Global Interpreter Lock` when
running an event loop.
.. note::
This module has been removed in Python 3.x.
.. exception:: AutoGILError
Raised if the observer callback cannot be installed, for example because the
current thread does not have a run loop.
.. function:: installAutoGIL()
Install an observer callback in the event loop (CFRunLoop) for the current
thread, that will lock and unlock the Global Interpreter Lock (GIL) at
appropriate times, allowing other Python threads to run while the event loop is
idle.
Availability: OSX 10.1 or later.

176
Doc/library/base64.rst Normal file
View File

@@ -0,0 +1,176 @@
: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 both base-64 alphabets defined
in :rfc:`3548` (normal, and URL- and filesystem-safe). 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 using 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* is
incorrectly padded. Characters that are neither
in the normal base-64 alphabet nor the alternative alphabet are
discarded prior to the padding check.
.. 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 the URL- and filesystem-safe
alphabet, which substitutes ``-`` instead of
``+`` and ``_`` instead of ``/`` in the standard Base64 alphabet. The result
can still contain ``=``.
.. function:: urlsafe_b64decode(s)
Decode string *s* using the URL- and filesystem-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* is
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.

305
Doc/library/basehttpserver.rst Normal file
View File

@@ -0,0 +1,305 @@
:mod:`BaseHTTPServer` --- Basic HTTP server
===========================================
.. module:: BaseHTTPServer
:synopsis: Basic HTTP server (base class for SimpleHTTPServer and CGIHTTPServer).
.. note::
The :mod:`BaseHTTPServer` module has been merged into :mod:`http.server` in
Python 3. The :term:`2to3` tool will automatically adapt imports when
converting your sources to Python 3.
.. index::
pair: WWW; server
pair: HTTP; protocol
single: URL
single: httpd
module: SimpleHTTPServer
module: CGIHTTPServer
**Source code:** :source:`Lib/BaseHTTPServer.py`
--------------
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, and therefore implements the :class:`SocketServer.BaseServer`
interface. 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:: client_address
Contains a tuple of the form ``(host, port)`` referring to the client's
address.
.. attribute:: server
Contains the server instance.
.. attribute:: command
Contains the command (request type). For example, ``'GET'``.
.. attribute:: path
Contains the request path.
.. attribute:: request_version
Contains the version string from the request. For example, ``'HTTP/1.0'``.
.. attribute:: 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:: rfile
Contains an input stream, positioned at the start of the optional input
data.
.. attribute:: 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:: 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:: 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:: 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:: error_content_type
Specifies the Content-Type HTTP header of error responses sent to the
client. The default value is ``'text/html'``.
.. versionadded:: 2.6
Previously, the content type was always ``'text/html'``.
.. attribute:: 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:: 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:: 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:: 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:: 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:: 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. The body will be empty
if the method is HEAD or the response code is one of the following:
``1xx``, ``204 No Content``, ``205 Reset Content``,
``304 Not Modified``.
.. method:: 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:: 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:: end_headers()
Sends a blank line, indicating the end of the HTTP headers in the
response.
.. method:: 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:: 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:: 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
ip address and current date and time are prefixed to every message logged.
.. method:: 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:: 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:: log_date_time_string()
Returns the current date and time, formatted for logging.
.. method:: address_string()
Returns the client address, formatted for logging. A name lookup is
performed on the client's IP address.
More examples
-------------
To create a server that doesn't run forever, but until some condition is
fulfilled::
def run_while_true(server_class=BaseHTTPServer.HTTPServer,
handler_class=BaseHTTPServer.BaseHTTPRequestHandler):
"""
This assumes that keep_running() is a function of no arguments which
is tested initially and after each request. If its return value
is true, the server continues.
"""
server_address = ('', 8000)
httpd = server_class(server_address, handler_class)
while keep_running():
httpd.handle_request()
.. 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.

64
Doc/library/bastion.rst Normal file
View File

@@ -0,0 +1,64 @@
:mod:`Bastion` --- Restricting access to objects
================================================
.. module:: Bastion
:synopsis: Providing restricted access to objects.
:deprecated:
.. deprecated:: 2.6
The :mod:`Bastion` module has been removed in Python 3.
.. moduleauthor:: Barry Warsaw <bwarsaw@python.org>
.. versionchanged:: 2.3
Disabled module.
.. note::
The documentation has been left in place to help in reading old code that uses
the module.
According to the dictionary, a bastion is "a fortified area or position", or
"something that is considered a stronghold." It's a suitable name for this
module, which provides a way to forbid access to certain attributes of an
object. It must always be used with the :mod:`rexec` module, in order to allow
restricted-mode programs access to certain safe attributes of an object, while
denying access to other, unsafe attributes.
.. I'm concerned that the word 'bastion' won't be understood by people
.. for whom English is a second language, making the module name
.. somewhat mysterious. Thus, the brief definition... --amk
.. I've punted on the issue of documenting keyword arguments for now.
.. function:: Bastion(object[, filter[, name[, class]]])
Protect the object *object*, returning a bastion for the object. Any attempt to
access one of the object's attributes will have to be approved by the *filter*
function; if the access is denied an :exc:`AttributeError` exception will be
raised.
If present, *filter* must be a function that accepts a string containing an
attribute name, and returns true if access to that attribute will be permitted;
if *filter* returns false, the access is denied. The default filter denies
access to any function beginning with an underscore (``'_'``). The bastion's
string representation will be ``<Bastion for name>`` if a value for *name* is
provided; otherwise, ``repr(object)`` will be used.
*class*, if present, should be a subclass of :class:`BastionClass`; see the
code in :file:`bastion.py` for the details. Overriding the default
:class:`BastionClass` will rarely be required.
.. class:: BastionClass(getfunc, name)
Class which actually implements bastion objects. This is the default class used
by :func:`Bastion`. The *getfunc* parameter is a function which returns the
value of an attribute which should be exposed to the restricted execution
environment when called with the name of the attribute as the only parameter.
*name* is used to construct the :func:`repr` of the :class:`BastionClass`
instance.

355
Doc/library/bdb.rst Normal file
View File

@@ -0,0 +1,355 @@
:mod:`bdb` --- Debugger framework
=================================
.. module:: bdb
:synopsis: Debugger framework.
**Source code:** :source:`Lib/bdb.py`
--------------
The :mod:`bdb` module handles basic debugger functions, like setting breakpoints
or managing execution via the debugger.
The following exception is defined:
.. exception:: BdbQuit
Exception raised by the :class:`Bdb` class for quitting the debugger.
The :mod:`bdb` module also defines two classes:
.. class:: Breakpoint(self, file, line, temporary=0, cond=None, funcname=None)
This class implements temporary breakpoints, ignore counts, disabling and
(re-)enabling, and conditionals.
Breakpoints are indexed by number through a list called :attr:`bpbynumber`
and by ``(file, line)`` pairs through :attr:`bplist`. The former points to a
single instance of class :class:`Breakpoint`. The latter points to a list of
such instances since there may be more than one breakpoint per line.
When creating a breakpoint, its associated filename should be in canonical
form. If a *funcname* is defined, a breakpoint hit will be counted when the
first line of that function is executed. A conditional breakpoint always
counts a hit.
:class:`Breakpoint` instances have the following methods:
.. method:: deleteMe()
Delete the breakpoint from the list associated to a file/line. If it is
the last breakpoint in that position, it also deletes the entry for the
file/line.
.. method:: enable()
Mark the breakpoint as enabled.
.. method:: disable()
Mark the breakpoint as disabled.
.. method:: pprint([out])
Print all the information about the breakpoint:
* The breakpoint number.
* If it is temporary or not.
* Its file,line position.
* The condition that causes a break.
* If it must be ignored the next N times.
* The breakpoint hit count.
.. class:: Bdb(skip=None)
The :class:`Bdb` class acts as a generic Python debugger base class.
This class takes care of the details of the trace facility; a derived class
should implement user interaction. The standard debugger class
(:class:`pdb.Pdb`) is an example.
The *skip* argument, if given, must be an iterable of glob-style
module name patterns. The debugger will not step into frames that
originate in a module that matches one of these patterns. Whether a
frame is considered to originate in a certain module is determined
by the ``__name__`` in the frame globals.
.. versionadded:: 2.7
The *skip* argument.
The following methods of :class:`Bdb` normally don't need to be overridden.
.. method:: canonic(filename)
Auxiliary method for getting a filename in a canonical form, that is, as a
case-normalized (on case-insensitive filesystems) absolute path, stripped
of surrounding angle brackets.
.. method:: reset()
Set the :attr:`botframe`, :attr:`stopframe`, :attr:`returnframe` and
:attr:`quitting` attributes with values ready to start debugging.
.. method:: trace_dispatch(frame, event, arg)
This function is installed as the trace function of debugged frames. Its
return value is the new trace function (in most cases, that is, itself).
The default implementation decides how to dispatch a frame, depending on
the type of event (passed as a string) that is about to be executed.
*event* can be one of the following:
* ``"line"``: A new line of code is going to be executed.
* ``"call"``: A function is about to be called, or another code block
entered.
* ``"return"``: A function or other code block is about to return.
* ``"exception"``: An exception has occurred.
* ``"c_call"``: A C function is about to be called.
* ``"c_return"``: A C function has returned.
* ``"c_exception"``: A C function has raised an exception.
For the Python events, specialized functions (see below) are called. For
the C events, no action is taken.
The *arg* parameter depends on the previous event.
See the documentation for :func:`sys.settrace` for more information on the
trace function. For more information on code and frame objects, refer to
:ref:`types`.
.. method:: dispatch_line(frame)
If the debugger should stop on the current line, invoke the
:meth:`user_line` method (which should be overridden in subclasses).
Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set
(which can be set from :meth:`user_line`). Return a reference to the
:meth:`trace_dispatch` method for further tracing in that scope.
.. method:: dispatch_call(frame, arg)
If the debugger should stop on this function call, invoke the
:meth:`user_call` method (which should be overridden in subclasses).
Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set
(which can be set from :meth:`user_call`). Return a reference to the
:meth:`trace_dispatch` method for further tracing in that scope.
.. method:: dispatch_return(frame, arg)
If the debugger should stop on this function return, invoke the
:meth:`user_return` method (which should be overridden in subclasses).
Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set
(which can be set from :meth:`user_return`). Return a reference to the
:meth:`trace_dispatch` method for further tracing in that scope.
.. method:: dispatch_exception(frame, arg)
If the debugger should stop at this exception, invokes the
:meth:`user_exception` method (which should be overridden in subclasses).
Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set
(which can be set from :meth:`user_exception`). Return a reference to the
:meth:`trace_dispatch` method for further tracing in that scope.
Normally derived classes don't override the following methods, but they may
if they want to redefine the definition of stopping and breakpoints.
.. method:: stop_here(frame)
This method checks if the *frame* is somewhere below :attr:`botframe` in
the call stack. :attr:`botframe` is the frame in which debugging started.
.. method:: break_here(frame)
This method checks if there is a breakpoint in the filename and line
belonging to *frame* or, at least, in the current function. If the
breakpoint is a temporary one, this method deletes it.
.. method:: break_anywhere(frame)
This method checks if there is a breakpoint in the filename of the current
frame.
Derived classes should override these methods to gain control over debugger
operation.
.. method:: user_call(frame, argument_list)
This method is called from :meth:`dispatch_call` when there is the
possibility that a break might be necessary anywhere inside the called
function.
.. method:: user_line(frame)
This method is called from :meth:`dispatch_line` when either
:meth:`stop_here` or :meth:`break_here` yields ``True``.
.. method:: user_return(frame, return_value)
This method is called from :meth:`dispatch_return` when :meth:`stop_here`
yields ``True``.
.. method:: user_exception(frame, exc_info)
This method is called from :meth:`dispatch_exception` when
:meth:`stop_here` yields ``True``.
.. method:: do_clear(arg)
Handle how a breakpoint must be removed when it is a temporary one.
This method must be implemented by derived classes.
Derived classes and clients can call the following methods to affect the
stepping state.
.. method:: set_step()
Stop after one line of code.
.. method:: set_next(frame)
Stop on the next line in or below the given frame.
.. method:: set_return(frame)
Stop when returning from the given frame.
.. method:: set_until(frame)
Stop when the line with the line no greater than the current one is
reached or when returning from current frame.
.. method:: set_trace([frame])
Start debugging from *frame*. If *frame* is not specified, debugging
starts from caller's frame.
.. method:: set_continue()
Stop only at breakpoints or when finished. If there are no breakpoints,
set the system trace function to ``None``.
.. method:: set_quit()
Set the :attr:`quitting` attribute to ``True``. This raises :exc:`BdbQuit` in
the next call to one of the :meth:`dispatch_\*` methods.
Derived classes and clients can call the following methods to manipulate
breakpoints. These methods return a string containing an error message if
something went wrong, or ``None`` if all is well.
.. method:: set_break(filename, lineno, temporary=0, cond=None, funcname=None)
Set a new breakpoint. If the *lineno* line doesn't exist for the
*filename* passed as argument, return an error message. The *filename*
should be in canonical form, as described in the :meth:`canonic` method.
.. method:: clear_break(filename, lineno)
Delete the breakpoints in *filename* and *lineno*. If none were set, an
error message is returned.
.. method:: clear_bpbynumber(arg)
Delete the breakpoint which has the index *arg* in the
:attr:`Breakpoint.bpbynumber`. If *arg* is not numeric or out of range,
return an error message.
.. method:: clear_all_file_breaks(filename)
Delete all breakpoints in *filename*. If none were set, an error message
is returned.
.. method:: clear_all_breaks()
Delete all existing breakpoints.
.. method:: get_break(filename, lineno)
Check if there is a breakpoint for *lineno* of *filename*.
.. method:: get_breaks(filename, lineno)
Return all breakpoints for *lineno* in *filename*, or an empty list if
none are set.
.. method:: get_file_breaks(filename)
Return all breakpoints in *filename*, or an empty list if none are set.
.. method:: get_all_breaks()
Return all breakpoints that are set.
Derived classes and clients can call the following methods to get a data
structure representing a stack trace.
.. method:: get_stack(f, t)
Get a list of records for a frame and all higher (calling) and lower
frames, and the size of the higher part.
.. method:: format_stack_entry(frame_lineno, [lprefix=': '])
Return a string with information about a stack entry, identified by a
``(frame, lineno)`` tuple:
* The canonical form of the filename which contains the frame.
* The function name, or ``"<lambda>"``.
* The input arguments.
* The return value.
* The line of code (if it exists).
The following two methods can be called by clients to use a debugger to debug
a :term:`statement`, given as a string.
.. method:: run(cmd, [globals, [locals]])
Debug a statement executed via the :keyword:`exec` statement. *globals*
defaults to :attr:`__main__.__dict__`, *locals* defaults to *globals*.
.. method:: runeval(expr, [globals, [locals]])
Debug an expression executed via the :func:`eval` function. *globals* and
*locals* have the same meaning as in :meth:`run`.
.. method:: runctx(cmd, globals, locals)
For backwards compatibility. Calls the :meth:`run` method.
.. method:: runcall(func, *args, **kwds)
Debug a single function call, and return its result.
Finally, the module defines the following functions:
.. function:: checkfuncname(b, frame)
Check whether we should break here, depending on the way the breakpoint *b*
was set.
If it was set via line number, it checks if ``b.line`` is the same as the one
in the frame also passed as argument. If the breakpoint was set via function
name, we have to check we are in the right frame (the right function) and if
we are in its first executable line.
.. function:: effective(file, line, frame)
Determine if there is an effective (active) breakpoint at this line of code.
Return a tuple of the breakpoint and a boolean that indicates if it is ok
to delete a temporary breakpoint. Return ``(None, None)`` if there is no
matching breakpoint.
.. function:: set_trace()
Start debugging with a :class:`Bdb` instance from caller's frame.

182
Doc/library/binascii.rst Normal file
View File

@@ -0,0 +1,182 @@
: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 newline is
added because the original use case for this function was to feed it a
series of 57 byte input lines to get output lines that conform to the
MIME-base64 standard. Otherwise the output conforms to :rfc:`3548`.
.. 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 a 16-bit CRC value of *data*, starting with an initial *crc* and
returning the result. This uses the CRC-CCITT polynomial
*x*:sup:`16` + *x*:sup:`12` + *x*:sup:`5` + 1, often represented as
0x1021. This CRC is used in the binhex4 format.
.. 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) & 0xffffffff
print 'crc32 = 0x%08x' % crc
.. note::
To generate the same numeric value across all Python versions and
platforms use crc32(data) & 0xffffffff. If you are only using
the checksum in packed binary format this is not necessary as the
return value is the correct 32bit binary representation
regardless of sign.
.. versionchanged:: 2.6
The return value is in the range [-2**31, 2**31-1]
regardless of platform. In the past the value would be signed on
some platforms and unsigned on others. Use & 0xffffffff on the
value if you want it to match Python 3 behavior.
.. versionchanged:: 3.0
The return value is unsigned and in the range [0, 2**32-1]
regardless of platform.
.. 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 RFC compliant base64-style encoding in base 16, 32, and 64.
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.

63
Doc/library/binhex.rst Normal file
View File

@@ -0,0 +1,63 @@
: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.
.. note::
In Python 3.x, special Macintosh support has been removed.
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 old Macintosh newline convention (carriage-return as end of line).
As of this writing, :func:`hexbin` appears to not work in all cases.

151
Doc/library/bisect.rst Normal file
View File

@@ -0,0 +1,151 @@
:mod:`bisect` --- Array bisection algorithm
===========================================
.. module:: bisect
:synopsis: Array bisection algorithms for binary searching.
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. sectionauthor:: Raymond Hettinger <python at rcn.com>
.. example based on the PyModules FAQ entry by Aaron Watters <arw@pythonpros.com>
.. versionadded:: 2.1
**Source code:** :source:`Lib/bisect.py`
--------------
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(a, x, lo=0, hi=len(a))
Locate the insertion point for *x* in *a* 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 *x* is
already present in *a*, 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()`` assuming that *a* is already sorted.
The returned insertion point *i* partitions the array *a* into two halves so
that ``all(val < x for val in a[lo:i])`` for the left side and
``all(val >= x for val in a[i:hi])`` for the right side.
.. function:: bisect_right(a, x, lo=0, hi=len(a))
bisect(a, x, lo=0, hi=len(a))
Similar to :func:`bisect_left`, but returns an insertion point which comes
after (to the right of) any existing entries of *x* in *a*.
The returned insertion point *i* partitions the array *a* into two halves so
that ``all(val <= x for val in a[lo:i])`` for the left side and
``all(val > x for val in a[i:hi])`` for the right side.
.. function:: insort_left(a, x, lo=0, hi=len(a))
Insert *x* in *a* in sorted order. This is equivalent to
``a.insert(bisect.bisect_left(a, x, lo, hi), x)`` assuming that *a* is
already sorted. Keep in mind that the O(log n) search is dominated by
the slow O(n) insertion step.
.. function:: insort_right(a, x, lo=0, hi=len(a))
insort(a, x, lo=0, hi=len(a))
Similar to :func:`insort_left`, but inserting *x* in *a* after any existing
entries of *x*.
.. seealso::
`SortedCollection recipe
<https://code.activestate.com/recipes/577197-sortedcollection/>`_ that uses
bisect to build a full-featured collection class with straight-forward search
methods and support for a key-function. The keys are precomputed to save
unnecessary calls to the key function during searches.
Searching Sorted Lists
----------------------
The above :func:`bisect` functions are useful for finding insertion points but
can be tricky or awkward to use for common searching tasks. The following five
functions show how to transform them into the standard lookups for sorted
lists::
def index(a, x):
'Locate the leftmost value exactly equal to x'
i = bisect_left(a, x)
if i != len(a) and a[i] == x:
return i
raise ValueError
def find_lt(a, x):
'Find rightmost value less than x'
i = bisect_left(a, x)
if i:
return a[i-1]
raise ValueError
def find_le(a, x):
'Find rightmost value less than or equal to x'
i = bisect_right(a, x)
if i:
return a[i-1]
raise ValueError
def find_gt(a, x):
'Find leftmost value greater than x'
i = bisect_right(a, x)
if i != len(a):
return a[i]
raise ValueError
def find_ge(a, x):
'Find leftmost item greater than or equal to x'
i = bisect_left(a, x)
if i != len(a):
return a[i]
raise ValueError
Other Examples
--------------
.. _bisect-example:
The :func:`bisect` function can be useful for numeric table lookups. This
example uses :func:`bisect` to look up a letter grade for an exam score (say)
based on a set of ordered numeric breakpoints: 90 and up is an 'A', 80 to 89 is
a 'B', and so on::
>>> def grade(score, breakpoints=[60, 70, 80, 90], grades='FDCBA'):
i = bisect(breakpoints, score)
return grades[i]
>>> [grade(score) for score in [33, 99, 77, 70, 89, 90, 100]]
['F', 'A', 'C', 'C', 'B', 'A', 'A']
Unlike the :func:`sorted` function, it does not make sense for the :func:`bisect`
functions to have *key* or *reversed* arguments because that would lead to an
inefficient design (successive calls to bisect functions would not "remember"
all of the previous key lookups).
Instead, it is better to search a list of precomputed keys to find the index
of the record in question::
>>> data = [('red', 5), ('blue', 1), ('yellow', 8), ('black', 0)]
>>> data.sort(key=lambda r: r[1])
>>> keys = [r[1] for r in data] # precomputed list of keys
>>> data[bisect_left(keys, 0)]
('black', 0)
>>> data[bisect_left(keys, 1)]
('blue', 1)
>>> data[bisect_left(keys, 5)]
('red', 5)
>>> data[bisect_left(keys, 8)]
('yellow', 8)

206
Doc/library/bsddb.rst Normal file
View File

@@ -0,0 +1,206 @@
:mod:`bsddb` --- Interface to Berkeley DB library
=================================================
.. module:: bsddb
:synopsis: Interface to Berkeley DB database library
.. sectionauthor:: Skip Montanaro <skip@pobox.com>
.. deprecated:: 2.6
The :mod:`bsddb` module has been removed in Python 3.
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 4.0 thru
4.7.
.. seealso::
http://www.jcea.es/programacion/pybsddb.htm
The website with documentation for the :mod:`bsddb.db` Python Berkeley DB
interface that closely mirrors the object oriented interface provided in
Berkeley DB 4.x itself.
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 :c:func:`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.
.. note::
Beginning in 2.3 some Unix versions of Python may have a :mod:`bsddb185` module.
This is present *only* to allow backwards compatibility with systems which ship
with the old Berkeley DB 1.85 database library. The :mod:`bsddb185` module
should never be used directly in new code. The module has been removed in
Python 3. If you find you still need it look in PyPI.
.. 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('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

219
Doc/library/bz2.rst Normal file
View File

@@ -0,0 +1,219 @@
: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 summary of the features offered by the bz2 module:
* :class:`BZ2File` class implements a complete file interface, including
:meth:`~BZ2File.readline`, :meth:`~BZ2File.readlines`,
:meth:`~BZ2File.writelines`, :meth:`~BZ2File.seek`, etc;
* :class:`BZ2File` class implements emulated :meth:`~BZ2File.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.
.. note::
Handling of multi-stream bzip2 files is not supported. Modules such as
`bz2file <https://github.com/nvawda/bz2file>`_ let you overcome this.
(De)compression of files
------------------------
Handling of compressed files is offered by the :class:`BZ2File` class.
.. index::
single: universal newlines; bz2.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
in :term:`universal newlines` mode. 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.
:class:`BZ2File` supports the :keyword:`with` statement.
.. versionchanged:: 2.7
Support for the :keyword:`with` statement was added.
.. note::
This class does not support input files containing multiple streams (such
as those produced by the :program:`pbzip2` tool). When reading such an
input file, only the first stream will be accessible. If you require
support for multi-stream files, consider using the third-party
:mod:`bz2file` module (available from
`PyPI <https://pypi.org/project/bz2file>`_). This module provides a
backport of Python 3.3's :class:`BZ2File` class, which does support
multi-stream files.
.. method:: 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:: 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:: 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:: 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:: xreadlines()
For backward compatibility. :class:`BZ2File` objects now include the
performance optimizations previously implemented in the :mod:`xreadlines`
module.
.. deprecated:: 2.3
This exists only for compatibility with the method by this name on
:class:`file` objects, which is deprecated. Use ``for line in file``
instead.
.. method:: 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:: tell()
Return the current file position, an integer (may be a long integer).
.. method:: 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:: 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:: 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:: 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:: 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.

340
Doc/library/calendar.rst Normal file
View File

@@ -0,0 +1,340 @@
: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>
**Source code:** :source:`Lib/calendar.py`
--------------
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. For related
functionality, see also the :mod:`datetime` and :mod:`time` modules.
Most of these functions and classes 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:: iterweekdays()
Return an iterator for the week day numbers that will be used for one
week. The first value from the iterator will be the same as the value of
the :attr:`firstweekday` property.
.. method:: 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:: 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:: 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:: 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:: 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:: 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:: yeardatescalendar(year[, 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:: yeardays2calendar(year[, 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:: yeardayscalendar(year[, 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:: 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 specified in the constructor or set by the
:meth:`setfirstweekday` method.
.. method:: prmonth(theyear, themonth[, w[, l]])
Print a month's calendar as returned by :meth:`formatmonth`.
.. method:: formatyear(theyear[, 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 specified in the constructor or set by the
:meth:`setfirstweekday` method. The earliest year for which a calendar
can be generated is platform-dependent.
.. method:: 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:: 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:: formatyear(theyear[, width])
Return a year's calendar as an HTML table. *width* (defaulting to 3)
specifies the number of months per row.
.. method:: formatyearpage(theyear[, 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
.. note::
The :meth:`formatweekday` and :meth:`formatmonthname` methods of these two
classes temporarily change the current locale to the given *locale*. Because
the current locale is a process-wide setting, they are not thread-safe.
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 from *y1* to *y2* (exclusive),
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:`~time.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.

576
Doc/library/carbon.rst Normal file
View File

@@ -0,0 +1,576 @@
.. _toolbox:
**********************
Mac OS Toolbox Modules
**********************
These are a set of modules that provide interfaces to various legacy Mac OS toolboxes.
If applicable the module will define a number of Python objects for the various
structures declared by the toolbox, and operations will be implemented as
methods of the object. Other operations will be implemented as functions in the
module. Not all operations possible in C will also be possible in Python
(callbacks are often a problem), and parameters will occasionally be different
in Python (input and output buffers, especially). All methods and functions
have a :attr:`__doc__` string describing their arguments and return values, and
for additional description you are referred to `Inside Macintosh
<http://developer.apple.com/legacy/mac/library/#documentation/macos8/mac8.html>`_ or similar works.
These modules all live in a package called :mod:`Carbon`. Despite that name they
are not all part of the Carbon framework: CF is really in the CoreFoundation
framework and Qt is in the QuickTime framework. The normal use pattern is ::
from Carbon import AE
.. note::
Most of the OS X APIs that these modules use are deprecated or removed
in recent versions of OS X. Many are not available when Python is
executing in 64-bit mode. The Carbon modules have been removed in
Python 3. You should avoid using them in Python 2.
:mod:`Carbon.AE` --- Apple Events
=================================
.. module:: Carbon.AE
:platform: Mac
:synopsis: Interface to the Apple Events toolbox.
:deprecated:
:mod:`Carbon.AH` --- Apple Help
===============================
.. module:: Carbon.AH
:platform: Mac
:synopsis: Interface to the Apple Help manager.
:deprecated:
:mod:`Carbon.App` --- Appearance Manager
========================================
.. module:: Carbon.App
:platform: Mac
:synopsis: Interface to the Appearance Manager.
:deprecated:
:mod:`Carbon.Appearance` --- Appearance Manager constants
=========================================================
.. module:: Carbon.Appearance
:platform: Mac
:synopsis: Constant definitions for the interface to the Appearance Manager.
:deprecated:
:mod:`Carbon.CF` --- Core Foundation
====================================
.. module:: Carbon.CF
:platform: Mac
:synopsis: Interface to the Core Foundation.
:deprecated:
The ``CFBase``, ``CFArray``, ``CFData``, ``CFDictionary``, ``CFString`` and
``CFURL`` objects are supported, some only partially.
:mod:`Carbon.CG` --- Core Graphics
==================================
.. module:: Carbon.CG
:platform: Mac
:synopsis: Interface to Core Graphics.
:deprecated:
:mod:`Carbon.CarbonEvt` --- Carbon Event Manager
================================================
.. module:: Carbon.CarbonEvt
:platform: Mac
:synopsis: Interface to the Carbon Event Manager.
:deprecated:
:mod:`Carbon.CarbonEvents` --- Carbon Event Manager constants
=============================================================
.. module:: Carbon.CarbonEvents
:platform: Mac
:synopsis: Constants for the interface to the Carbon Event Manager.
:deprecated:
:mod:`Carbon.Cm` --- Component Manager
======================================
.. module:: Carbon.Cm
:platform: Mac
:synopsis: Interface to the Component Manager.
:deprecated:
:mod:`Carbon.Components` --- Component Manager constants
========================================================
.. module:: Carbon.Components
:platform: Mac
:synopsis: Constants for the interface to the Component Manager.
:deprecated:
:mod:`Carbon.ControlAccessor` --- Control Manager accssors
===========================================================
.. module:: Carbon.ControlAccessor
:platform: Mac
:synopsis: Accessor functions for the interface to the Control Manager.
:deprecated:
:mod:`Carbon.Controls` --- Control Manager constants
====================================================
.. module:: Carbon.Controls
:platform: Mac
:synopsis: Constants for the interface to the Control Manager.
:deprecated:
:mod:`Carbon.CoreFounation` --- CoreFounation constants
=======================================================
.. module:: Carbon.CoreFounation
:platform: Mac
:synopsis: Constants for the interface to CoreFoundation.
:deprecated:
:mod:`Carbon.CoreGraphics` --- CoreGraphics constants
=======================================================
.. module:: Carbon.CoreGraphics
:platform: Mac
:synopsis: Constants for the interface to CoreGraphics.
:deprecated:
:mod:`Carbon.Ctl` --- Control Manager
=====================================
.. module:: Carbon.Ctl
:platform: Mac
:synopsis: Interface to the Control Manager.
:deprecated:
:mod:`Carbon.Dialogs` --- Dialog Manager constants
==================================================
.. module:: Carbon.Dialogs
:platform: Mac
:synopsis: Constants for the interface to the Dialog Manager.
:deprecated:
:mod:`Carbon.Dlg` --- Dialog Manager
====================================
.. module:: Carbon.Dlg
:platform: Mac
:synopsis: Interface to the Dialog Manager.
:deprecated:
:mod:`Carbon.Drag` --- Drag and Drop Manager
=============================================
.. module:: Carbon.Drag
:platform: Mac
:synopsis: Interface to the Drag and Drop Manager.
:deprecated:
:mod:`Carbon.Dragconst` --- Drag and Drop Manager constants
===========================================================
.. module:: Carbon.Dragconst
:platform: Mac
:synopsis: Constants for the interface to the Drag and Drop Manager.
:deprecated:
:mod:`Carbon.Events` --- Event Manager constants
================================================
.. module:: Carbon.Events
:platform: Mac
:synopsis: Constants for the interface to the classic Event Manager.
:deprecated:
:mod:`Carbon.Evt` --- Event Manager
===================================
.. module:: Carbon.Evt
:platform: Mac
:synopsis: Interface to the classic Event Manager.
:deprecated:
:mod:`Carbon.File` --- File Manager
===================================
.. module:: Carbon.File
:platform: Mac
:synopsis: Interface to the File Manager.
:deprecated:
:mod:`Carbon.Files` --- File Manager constants
==============================================
.. module:: Carbon.Files
:platform: Mac
:synopsis: Constants for the interface to the File Manager.
:deprecated:
:mod:`Carbon.Fm` --- Font Manager
=================================
.. module:: Carbon.Fm
:platform: Mac
:synopsis: Interface to the Font Manager.
:deprecated:
:mod:`Carbon.Folder` --- Folder Manager
=======================================
.. module:: Carbon.Folder
:platform: Mac
:synopsis: Interface to the Folder Manager.
:deprecated:
:mod:`Carbon.Folders` --- Folder Manager constants
==================================================
.. module:: Carbon.Folders
:platform: Mac
:synopsis: Constants for the interface to the Folder Manager.
:deprecated:
:mod:`Carbon.Fonts` --- Font Manager constants
==================================================
.. module:: Carbon.Fonts
:platform: Mac
:synopsis: Constants for the interface to the Font Manager.
:deprecated:
:mod:`Carbon.Help` --- Help Manager
===================================
.. module:: Carbon.Help
:platform: Mac
:synopsis: Interface to the Carbon Help Manager.
:deprecated:
:mod:`Carbon.IBCarbon` --- Carbon InterfaceBuilder
==================================================
.. module:: Carbon.IBCarbon
:platform: Mac
:synopsis: Interface to the Carbon InterfaceBuilder support libraries.
:deprecated:
:mod:`Carbon.IBCarbonRuntime` --- Carbon InterfaceBuilder constants
===================================================================
.. module:: Carbon.IBCarbonRuntime
:platform: Mac
:synopsis: Constants for the interface to the Carbon InterfaceBuilder support libraries.
:deprecated:
:mod:`Carbon.Icn` --- Carbon Icon Manager
=========================================
.. module:: Carbon.Icns
:platform: Mac
:synopsis: Interface to the Carbon Icon Manager
:deprecated:
:mod:`Carbon.Icons` --- Carbon Icon Manager constants
=====================================================
.. module:: Carbon.Icons
:platform: Mac
:synopsis: Constants for the interface to the Carbon Icon Manager
:deprecated:
:mod:`Carbon.Launch` --- Carbon Launch Services
===============================================
.. module:: Carbon.Launch
:platform: Mac
:synopsis: Interface to the Carbon Launch Services.
:deprecated:
:mod:`Carbon.LaunchServices` --- Carbon Launch Services constants
=================================================================
.. module:: Carbon.LaunchServices
:platform: Mac
:synopsis: Constants for the interface to the Carbon Launch Services.
:deprecated:
:mod:`Carbon.List` --- List Manager
===================================
.. module:: Carbon.List
:platform: Mac
:synopsis: Interface to the List Manager.
:deprecated:
:mod:`Carbon.Lists` --- List Manager constants
==============================================
.. module:: Carbon.Lists
:platform: Mac
:synopsis: Constants for the interface to the List Manager.
:deprecated:
:mod:`Carbon.MacHelp` --- Help Manager constants
================================================
.. module:: Carbon.MacHelp
:platform: Mac
:synopsis: Constants for the interface to the Carbon Help Manager.
:deprecated:
:mod:`Carbon.MediaDescr` --- Parsers and generators for Quicktime Media descriptors
===================================================================================
.. module:: Carbon.MediaDescr
:platform: Mac
:synopsis: Parsers and generators for Quicktime Media descriptors
:deprecated:
:mod:`Carbon.Menu` --- Menu Manager
===================================
.. module:: Carbon.Menu
:platform: Mac
:synopsis: Interface to the Menu Manager.
:deprecated:
:mod:`Carbon.Menus` --- Menu Manager constants
==============================================
.. module:: Carbon.Menus
:platform: Mac
:synopsis: Constants for the interface to the Menu Manager.
:deprecated:
:mod:`Carbon.Mlte` --- MultiLingual Text Editor
===============================================
.. module:: Carbon.Mlte
:platform: Mac
:synopsis: Interface to the MultiLingual Text Editor.
:deprecated:
:mod:`Carbon.OSA` --- Carbon OSA Interface
==========================================
.. module:: Carbon.OSA
:platform: Mac
:synopsis: Interface to the Carbon OSA Library.
:deprecated:
:mod:`Carbon.OSAconst` --- Carbon OSA Interface constants
=========================================================
.. module:: Carbon.OSAconst
:platform: Mac
:synopsis: Constants for the interface to the Carbon OSA Library.
:deprecated:
:mod:`Carbon.QDOffscreen` --- QuickDraw Offscreen constants
===========================================================
.. module:: Carbon.QDOffscreen
:platform: Mac
:synopsis: Constants for the interface to the QuickDraw Offscreen APIs.
:deprecated:
:mod:`Carbon.Qd` --- QuickDraw
==============================
.. module:: Carbon.Qd
:platform: Mac
:synopsis: Interface to the QuickDraw toolbox.
:deprecated:
:mod:`Carbon.Qdoffs` --- QuickDraw Offscreen
============================================
.. module:: Carbon.Qdoffs
:platform: Mac
:synopsis: Interface to the QuickDraw Offscreen APIs.
:deprecated:
:mod:`Carbon.Qt` --- QuickTime
==============================
.. module:: Carbon.Qt
:platform: Mac
:synopsis: Interface to the QuickTime toolbox.
:deprecated:
:mod:`Carbon.QuickDraw` --- QuickDraw constants
===============================================
.. module:: Carbon.QuickDraw
:platform: Mac
:synopsis: Constants for the interface to the QuickDraw toolbox.
:deprecated:
:mod:`Carbon.QuickTime` --- QuickTime constants
===============================================
.. module:: Carbon.QuickTime
:platform: Mac
:synopsis: Constants for the interface to the QuickTime toolbox.
:deprecated:
:mod:`Carbon.Res` --- Resource Manager and Handles
==================================================
.. module:: Carbon.Res
:platform: Mac
:synopsis: Interface to the Resource Manager and Handles.
:deprecated:
:mod:`Carbon.Resources` --- Resource Manager and Handles constants
==================================================================
.. module:: Carbon.Resources
:platform: Mac
:synopsis: Constants for the interface to the Resource Manager and Handles.
:deprecated:
:mod:`Carbon.Scrap` --- Scrap Manager
=====================================
.. module:: Carbon.Scrap
:platform: Mac
:synopsis: The Scrap Manager provides basic services for implementing cut & paste and
clipboard operations.
:deprecated:
This module is only fully available on Mac OS 9 and earlier under classic PPC
MacPython. Very limited functionality is available under Carbon MacPython.
.. index:: single: Scrap Manager
The Scrap Manager supports the simplest form of cut & paste operations on the
Macintosh. It can be use for both inter- and intra-application clipboard
operations.
The :mod:`Scrap` module provides low-level access to the functions of the Scrap
Manager. It contains the following functions:
.. function:: InfoScrap()
Return current information about the scrap. The information is encoded as a
tuple containing the fields ``(size, handle, count, state, path)``.
+----------+---------------------------------------------+
| Field | Meaning |
+==========+=============================================+
| *size* | Size of the scrap in bytes. |
+----------+---------------------------------------------+
| *handle* | Resource object representing the scrap. |
+----------+---------------------------------------------+
| *count* | Serial number of the scrap contents. |
+----------+---------------------------------------------+
| *state* | Integer; positive if in memory, ``0`` if on |
| | disk, negative if uninitialized. |
+----------+---------------------------------------------+
| *path* | Filename of the scrap when stored on disk. |
+----------+---------------------------------------------+
.. seealso::
`Scrap Manager <http://developer.apple.com/legacy/mac/library/documentation/mac/MoreToolbox/MoreToolbox-109.html>`_
Apple's documentation for the Scrap Manager gives a lot of useful information
about using the Scrap Manager in applications.
:mod:`Carbon.Snd` --- Sound Manager
===================================
.. module:: Carbon.Snd
:platform: Mac
:synopsis: Interface to the Sound Manager.
:deprecated:
:mod:`Carbon.Sound` --- Sound Manager constants
===============================================
.. module:: Carbon.Sound
:platform: Mac
:synopsis: Constants for the interface to the Sound Manager.
:deprecated:
:mod:`Carbon.TE` --- TextEdit
=============================
.. module:: Carbon.TE
:platform: Mac
:synopsis: Interface to TextEdit.
:deprecated:
:mod:`Carbon.TextEdit` --- TextEdit constants
=============================================
.. module:: Carbon.TextEdit
:platform: Mac
:synopsis: Constants for the interface to TextEdit.
:deprecated:
:mod:`Carbon.Win` --- Window Manager
====================================
.. module:: Carbon.Win
:platform: Mac
:synopsis: Interface to the Window Manager.
:deprecated:
:mod:`Carbon.Windows` --- Window Manager constants
==================================================
.. module:: Carbon.Windows
:platform: Mac
:synopsis: Constants for the interface to the Window Manager.
:deprecated:

340
Doc/library/cd.rst Normal file
View File

@@ -0,0 +1,340 @@
:mod:`cd` --- CD-ROM access on SGI systems
==========================================
.. module:: cd
:platform: IRIX
:synopsis: Interface to the CD-ROM on Silicon Graphics systems.
:deprecated:
.. deprecated:: 2.6
The :mod:`cd` module has been removed in Python 3.
This module provides an interface to the Silicon Graphics CD library. It is
available only on Silicon Graphics systems.
The way the library works is as follows. A program opens the CD-ROM device with
:func:`.open` and creates a parser to parse the data from the CD with
:func:`createparser`. The object returned by :func:`.open` can be used to read
data from the CD, but also to get status information for the CD-ROM device, and
to get information about the CD, such as the table of contents. Data from the
CD is passed to the parser, which parses the frames, and calls any callback
functions that have previously been added.
An audio CD is divided into :dfn:`tracks` or :dfn:`programs` (the terms are used
interchangeably). Tracks can be subdivided into :dfn:`indices`. An audio CD
contains a :dfn:`table of contents` which gives the starts of the tracks on the
CD. Index 0 is usually the pause before the start of a track. The start of the
track as given by the table of contents is normally the start of index 1.
Positions on a CD can be represented in two ways. Either a frame number or a
tuple of three values, minutes, seconds and frames. Most functions use the
latter representation. Positions can be both relative to the beginning of the
CD, and to the beginning of the track.
Module :mod:`cd` defines the following functions and constants:
.. function:: createparser()
Create and return an opaque parser object. The methods of the parser object are
described below.
.. function:: msftoframe(minutes, seconds, frames)
Converts a ``(minutes, seconds, frames)`` triple representing time in absolute
time code into the corresponding CD frame number.
.. function:: open([device[, mode]])
Open the CD-ROM device. The return value is an opaque player object; methods of
the player object are described below. The device is the name of the SCSI
device file, e.g. ``'/dev/scsi/sc0d4l0'``, or ``None``. If omitted or ``None``,
the hardware inventory is consulted to locate a CD-ROM drive. The *mode*, if
not omitted, should be the string ``'r'``.
The module defines the following variables:
.. exception:: error
Exception raised on various errors.
.. data:: DATASIZE
The size of one frame's worth of audio data. This is the size of the audio data
as passed to the callback of type ``audio``.
.. data:: BLOCKSIZE
The size of one uninterpreted frame of audio data.
The following variables are states as returned by :func:`getstatus`:
.. data:: READY
The drive is ready for operation loaded with an audio CD.
.. data:: NODISC
The drive does not have a CD loaded.
.. data:: CDROM
The drive is loaded with a CD-ROM. Subsequent play or read operations will
return I/O errors.
.. data:: ERROR
An error occurred while trying to read the disc or its table of contents.
.. data:: PLAYING
The drive is in CD player mode playing an audio CD through its audio jacks.
.. data:: PAUSED
The drive is in CD layer mode with play paused.
.. data:: STILL
The equivalent of :const:`PAUSED` on older (non 3301) model Toshiba CD-ROM
drives. Such drives have never been shipped by SGI.
.. data:: audio
pnum
index
ptime
atime
catalog
ident
control
Integer constants describing the various types of parser callbacks that can be
set by the :meth:`addcallback` method of CD parser objects (see below).
.. _player-objects:
Player Objects
--------------
Player objects (returned by :func:`.open`) have the following methods:
.. method:: CD player.allowremoval()
Unlocks the eject button on the CD-ROM drive permitting the user to eject the
caddy if desired.
.. method:: CD player.bestreadsize()
Returns the best value to use for the *num_frames* parameter of the
:meth:`readda` method. Best is defined as the value that permits a continuous
flow of data from the CD-ROM drive.
.. method:: CD player.close()
Frees the resources associated with the player object. After calling
:meth:`close`, the methods of the object should no longer be used.
.. method:: CD player.eject()
Ejects the caddy from the CD-ROM drive.
.. method:: CD player.getstatus()
Returns information pertaining to the current state of the CD-ROM drive. The
returned information is a tuple with the following values: *state*, *track*,
*rtime*, *atime*, *ttime*, *first*, *last*, *scsi_audio*, *cur_block*. *rtime*
is the time relative to the start of the current track; *atime* is the time
relative to the beginning of the disc; *ttime* is the total time on the disc.
For more information on the meaning of the values, see the man page
:manpage:`CDgetstatus(3dm)`. The value of *state* is one of the following:
:const:`ERROR`, :const:`NODISC`, :const:`READY`, :const:`PLAYING`,
:const:`PAUSED`, :const:`STILL`, or :const:`CDROM`.
.. method:: CD player.gettrackinfo(track)
Returns information about the specified track. The returned information is a
tuple consisting of two elements, the start time of the track and the duration
of the track.
.. method:: CD player.msftoblock(min, sec, frame)
Converts a minutes, seconds, frames triple representing a time in absolute time
code into the corresponding logical block number for the given CD-ROM drive.
You should use :func:`msftoframe` rather than :meth:`msftoblock` for comparing
times. The logical block number differs from the frame number by an offset
required by certain CD-ROM drives.
.. method:: CD player.play(start, play)
Starts playback of an audio CD in the CD-ROM drive at the specified track. The
audio output appears on the CD-ROM drive's headphone and audio jacks (if
fitted). Play stops at the end of the disc. *start* is the number of the track
at which to start playing the CD; if *play* is 0, the CD will be set to an
initial paused state. The method :meth:`togglepause` can then be used to
commence play.
.. method:: CD player.playabs(minutes, seconds, frames, play)
Like :meth:`play`, except that the start is given in minutes, seconds, and
frames instead of a track number.
.. method:: CD player.playtrack(start, play)
Like :meth:`play`, except that playing stops at the end of the track.
.. method:: CD player.playtrackabs(track, minutes, seconds, frames, play)
Like :meth:`play`, except that playing begins at the specified absolute time and
ends at the end of the specified track.
.. method:: CD player.preventremoval()
Locks the eject button on the CD-ROM drive thus preventing the user from
arbitrarily ejecting the caddy.
.. method:: CD player.readda(num_frames)
Reads the specified number of frames from an audio CD mounted in the CD-ROM
drive. The return value is a string representing the audio frames. This string
can be passed unaltered to the :meth:`parseframe` method of the parser object.
.. method:: CD player.seek(minutes, seconds, frames)
Sets the pointer that indicates the starting point of the next read of digital
audio data from a CD-ROM. The pointer is set to an absolute time code location
specified in *minutes*, *seconds*, and *frames*. The return value is the
logical block number to which the pointer has been set.
.. method:: CD player.seekblock(block)
Sets the pointer that indicates the starting point of the next read of digital
audio data from a CD-ROM. The pointer is set to the specified logical block
number. The return value is the logical block number to which the pointer has
been set.
.. method:: CD player.seektrack(track)
Sets the pointer that indicates the starting point of the next read of digital
audio data from a CD-ROM. The pointer is set to the specified track. The
return value is the logical block number to which the pointer has been set.
.. method:: CD player.stop()
Stops the current playing operation.
.. method:: CD player.togglepause()
Pauses the CD if it is playing, and makes it play if it is paused.
.. _cd-parser-objects:
Parser Objects
--------------
Parser objects (returned by :func:`createparser`) have the following methods:
.. method:: CD parser.addcallback(type, func, arg)
Adds a callback for the parser. The parser has callbacks for eight different
types of data in the digital audio data stream. Constants for these types are
defined at the :mod:`cd` module level (see above). The callback is called as
follows: ``func(arg, type, data)``, where *arg* is the user supplied argument,
*type* is the particular type of callback, and *data* is the data returned for
this *type* of callback. The type of the data depends on the *type* of callback
as follows:
+-------------+---------------------------------------------+
| Type | Value |
+=============+=============================================+
| ``audio`` | String which can be passed unmodified to |
| | :func:`al.writesamps`. |
+-------------+---------------------------------------------+
| ``pnum`` | Integer giving the program (track) number. |
+-------------+---------------------------------------------+
| ``index`` | Integer giving the index number. |
+-------------+---------------------------------------------+
| ``ptime`` | Tuple consisting of the program time in |
| | minutes, seconds, and frames. |
+-------------+---------------------------------------------+
| ``atime`` | Tuple consisting of the absolute time in |
| | minutes, seconds, and frames. |
+-------------+---------------------------------------------+
| ``catalog`` | String of 13 characters, giving the catalog |
| | number of the CD. |
+-------------+---------------------------------------------+
| ``ident`` | String of 12 characters, giving the ISRC |
| | identification number of the recording. |
| | The string consists of two characters |
| | country code, three characters owner code, |
| | two characters giving the year, and five |
| | characters giving a serial number. |
+-------------+---------------------------------------------+
| ``control`` | Integer giving the control bits from the CD |
| | subcode data |
+-------------+---------------------------------------------+
.. method:: CD parser.deleteparser()
Deletes the parser and frees the memory it was using. The object should not be
used after this call. This call is done automatically when the last reference
to the object is removed.
.. method:: CD parser.parseframe(frame)
Parses one or more frames of digital audio data from a CD such as returned by
:meth:`readda`. It determines which subcodes are present in the data. If these
subcodes have changed since the last frame, then :meth:`parseframe` executes a
callback of the appropriate type passing to it the subcode data found in the
frame. Unlike the C function, more than one frame of digital audio data can be
passed to this method.
.. method:: CD parser.removecallback(type)
Removes the callback for the given *type*.
.. method:: CD parser.resetparser()
Resets the fields of the parser used for tracking subcodes to an initial state.
:meth:`resetparser` should be called after the disc has been changed.

546
Doc/library/cgi.rst Normal file
View File

@@ -0,0 +1,546 @@
:mod:`cgi` --- Common Gateway Interface support
===============================================
.. module:: cgi
:synopsis: Helpers for running Python scripts via the Common Gateway Interface.
.. index::
pair: WWW; server
pair: CGI; protocol
pair: HTTP; protocol
pair: MIME; headers
single: URL
single: Common Gateway Interface
**Source code:** :source:`Lib/cgi.py`
--------------
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 these lines::
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 code like this::
import cgitb
cgitb.enable(display=0, logdir="/path/to/logdir")
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.
It allows membership testing with the :keyword:`in` operator, and also supports
the standard dictionary method :meth:`~dict.keys` and the built-in function
:func:`len`. 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 "name" not in form or "addr" not in form:
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:`~FieldStorage.value` attribute of the instance yields
the string value of the field. The :meth:`~FieldStorage.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 :meth:`~FieldStorage.getlist` method, 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:`~FieldStorage.value` attribute or the :func:`~FieldStorage.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:`~FieldStorage.filename` attribute or the :attr:`~FieldStorage.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
If an error is encountered when obtaining the contents of an uploaded file
(for example, when the user interrupts the form submission by clicking on
a Back or Cancel button) the :attr:`~FieldStorage.done` attribute of the
object for the field will be set to the value -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``.
A form submitted via POST that also has a query string will contain both
:class:`FieldStorage` and :class:`MiniFieldStorage` items.
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:`~str.upper` 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:`~FieldStorage.getfirst`
and :meth:`~FieldStorage.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
-----------
.. deprecated:: 2.6
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.
.. _functions-in-cgi-module:
Functions
---------
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[, environ[, keep_blank_values[, strict_parsing]]])
Parse a query in the environment or from a file (the file defaults to
``sys.stdin`` and environment defaults to ``os.environ``). The *keep_blank_values* and *strict_parsing* parameters are
passed to :func:`urlparse.parse_qs` unchanged.
.. function:: parse_qs(qs[, keep_blank_values[, strict_parsing[, max_num_fields]]])
This function is deprecated in this module. Use :func:`urlparse.parse_qs`
instead. It is maintained here only for backward compatibility.
.. function:: parse_qsl(qs[, keep_blank_values[, strict_parsing[, max_num_fields]]])
This function is deprecated in this module. Use :func:`urlparse.parse_qsl`
instead. It is maintained here only for backward compatibility.
.. 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:`urlparse.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 delimited by double quotes, as in ``<a href="...">``. Note
that single quotes are never translated.
If the value to be quoted might include single- or double-quote characters,
or both, consider using the :func:`~xml.sax.saxutils.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:
.. code-block:: none
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 lines::
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.

76
Doc/library/cgihttpserver.rst Normal file
View File

@@ -0,0 +1,76 @@
: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>
.. note::
The :mod:`CGIHTTPServer` module has been merged into :mod:`http.server` in
Python 3. The :term:`2to3` tool will automatically adapt imports when
converting your sources to Python 3.
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.
.. 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:: 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:: 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.

65
Doc/library/cgitb.rst Normal file
View File

@@ -0,0 +1,65 @@
: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 this 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`.

133
Doc/library/chunk.rst Normal file
View File

@@ -0,0 +1,133 @@
: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 an :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:`~file.read`. If the methods
:meth:`~file.seek` and :meth:`~file.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:: getname()
Returns the name (ID) of the chunk. This is the first 4 bytes of the
chunk.
.. method:: getsize()
Returns the size of the chunk.
.. method:: 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:: isatty()
Returns ``False``.
.. method:: 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:: tell()
Return the current position into the chunk.
.. method:: 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:: 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.

260
Doc/library/cmath.rst Normal file
View File

@@ -0,0 +1,260 @@
: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.
.. note::
On platforms with hardware and system-level support for signed
zeros, functions involving branch cuts are continuous on *both*
sides of the branch cut: the sign of the zero distinguishes one
side of the branch cut from the other. On platforms that do not
support signed zeros the continuity is as specified below.
Conversions to and from polar coordinates
-----------------------------------------
A Python complex number ``z`` is stored internally using *rectangular*
or *Cartesian* coordinates. It is completely determined by its *real
part* ``z.real`` and its *imaginary part* ``z.imag``. In other
words::
z == z.real + z.imag*1j
*Polar coordinates* give an alternative way to represent a complex
number. In polar coordinates, a complex number *z* is defined by the
modulus *r* and the phase angle *phi*. The modulus *r* is the distance
from *z* to the origin, while the phase *phi* is the counterclockwise
angle, measured in radians, from the positive x-axis to the line
segment that joins the origin to *z*.
The following functions can be used to convert from the native
rectangular coordinates to polar coordinates and back.
.. function:: phase(x)
Return the phase of *x* (also known as the *argument* of *x*), as a
float. ``phase(x)`` is equivalent to ``math.atan2(x.imag,
x.real)``. The result lies in the range [-π, π], and the branch
cut for this operation lies along the negative real axis,
continuous from above. On systems with support for signed zeros
(which includes most systems in current use), this means that the
sign of the result is the same as the sign of ``x.imag``, even when
``x.imag`` is zero::
>>> phase(complex(-1.0, 0.0))
3.1415926535897931
>>> phase(complex(-1.0, -0.0))
-3.1415926535897931
.. versionadded:: 2.6
.. note::
The modulus (absolute value) of a complex number *x* can be
computed using the built-in :func:`abs` function. There is no
separate :mod:`cmath` module function for this operation.
.. function:: polar(x)
Return the representation of *x* in polar coordinates. Returns a
pair ``(r, phi)`` where *r* is the modulus of *x* and phi is the
phase of *x*. ``polar(x)`` is equivalent to ``(abs(x),
phase(x))``.
.. versionadded:: 2.6
.. function:: rect(r, phi)
Return the complex number *x* with polar coordinates *r* and *phi*.
Equivalent to ``r * (math.cos(phi) + math.sin(phi)*1j)``.
.. versionadded:: 2.6
Power and logarithmic functions
-------------------------------
.. 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:: sqrt(x)
Return the square root of *x*. This has the same branch cut as :func:`log`.
Trigonometric functions
-----------------------
.. 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:: asin(x)
Return the arc sine of *x*. This has the same branch cuts as :func:`acos`.
.. 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 right. The
other extends from ``-1j`` along the imaginary axis to ``-∞j``, continuous
from the left.
.. versionchanged:: 2.6
direction of continuity of upper cut reversed
.. function:: cos(x)
Return the cosine of *x*.
.. function:: sin(x)
Return the sine of *x*.
.. function:: tan(x)
Return the tangent of *x*.
Hyperbolic functions
--------------------
.. function:: acosh(x)
Return the inverse hyperbolic cosine of *x*. There is one branch cut,
extending left from 1 along the real axis to -∞, continuous from above.
.. function:: asinh(x)
Return the inverse hyperbolic sine of *x*. There are two branch cuts:
One extends from ``1j`` along the imaginary axis to ``∞j``,
continuous from the right. The other extends from ``-1j`` along
the imaginary axis to ``-∞j``, continuous from the left.
.. versionchanged:: 2.6
branch cuts moved to match those recommended by the C99 standard
.. function:: atanh(x)
Return the inverse hyperbolic tangent of *x*. There are two branch cuts: One
extends from ``1`` along the real axis to ``∞``, continuous from below. The
other extends from ``-1`` along the real axis to ``-∞``, continuous from
above.
.. versionchanged:: 2.6
direction of continuity of right cut reversed
.. function:: cosh(x)
Return the hyperbolic cosine of *x*.
.. function:: sinh(x)
Return the hyperbolic sine of *x*.
.. function:: tanh(x)
Return the hyperbolic tangent of *x*.
Classification functions
------------------------
.. function:: isinf(x)
Return ``True`` if the real or the imaginary part of x is positive
or negative infinity.
.. versionadded:: 2.6
.. function:: isnan(x)
Return ``True`` if the real or imaginary part of x is not a number (NaN).
.. versionadded:: 2.6
Constants
---------
.. data:: pi
The mathematical constant *π*, as a float.
.. data:: e
The mathematical constant *e*, as a float.
.. 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.

217
Doc/library/cmd.rst Normal file
View File

@@ -0,0 +1,217 @@
:mod:`cmd` --- Support for line-oriented command interpreters
=============================================================
.. module:: cmd
:synopsis: Build line-oriented command interpreters.
.. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com>
**Source code:** :source:`Lib/cmd.py`
--------------
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 :data:`sys.stdin` and
:data:`sys.stdout`.
If you want a given *stdin* to be used, make sure to set the instance's
:attr:`use_rawinput` attribute to ``False``, otherwise *stdin* will be
ignored.
.. 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 attribute).
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`, and if that is not present, prints the docstring of
:meth:`do_bar`, if available. With no argument, :meth:`do_help` lists all
available help topics (that is, all commands with corresponding
:meth:`help_\*` methods or commands that have docstrings), 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.cmdqueue
A list of queued input lines. The cmdqueue list is checked in
:meth:`cmdloop` when new input is needed; if it is nonempty, its elements
will be processed in order, as if entered at the prompt.
.. 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:`raw_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/library/code.rst Normal file
View File

@@ -0,0 +1,167 @@
:mod:`code` --- Interpreter base classes
========================================
.. module:: code
:synopsis: Facilities to implement read-eval-print loops.
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:`InteractiveConsole.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 uses the built-in function :func:`raw_input`; a subclass
may replace this with a different implementation.

1318
Doc/library/codecs.rst Normal file
View File

File diff suppressed because it is too large Load Diff

93
Doc/library/codeop.rst Normal file
View File

@@ -0,0 +1,93 @@
: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>
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 :term:`expression` (``'eval'``). Any
other value will cause :exc:`ValueError` to be raised.
.. note::
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.

1054
Doc/library/collections.rst Normal file
View File

File diff suppressed because it is too large Load Diff

28
Doc/library/colorpicker.rst Normal file
View File

@@ -0,0 +1,28 @@
:mod:`ColorPicker` --- Color selection dialog
=============================================
.. module:: ColorPicker
:platform: Mac
:synopsis: Interface to the standard color selection dialog.
:deprecated:
.. moduleauthor:: Just van Rossum <just@letterror.com>
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
The :mod:`ColorPicker` module provides access to the standard color picker
dialog.
.. note::
This module has been removed in Python 3.x.
.. function:: GetColor(prompt, rgb)
Show a standard color selection dialog and allow the user to select a color.
The user is given instruction by the *prompt* string, and the default color is
set to *rgb*. *rgb* must be a tuple giving the red, green, and blue components
of the color. :func:`GetColor` returns a tuple giving the user's selected color
and a flag indicating whether they accepted the selection of cancelled.

64
Doc/library/colorsys.rst Normal file
View File

@@ -0,0 +1,64 @@
:mod:`colorsys` --- Conversions between color systems
=====================================================
.. module:: colorsys
:synopsis: Conversion functions between RGB and other color systems.
.. sectionauthor:: David Ascher <da@python.net>
**Source code:** :source:`Lib/colorsys.py`
--------------
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.
.. seealso::
More information about color spaces can be found at
https://www.poynton.com/ColorFAQ.html and
https://www.cambridgeincolour.com/tutorials/color-spaces.htm.
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(0.2, 0.4, 0.4)
(0.5, 0.5, 0.4)
>>> colorsys.hsv_to_rgb(0.5, 0.5, 0.4)
(0.2, 0.4, 0.4)

80
Doc/library/commands.rst Normal file
View File

@@ -0,0 +1,80 @@
:mod:`commands` --- Utilities for running commands
==================================================
.. module:: commands
:platform: Unix
:synopsis: Utility functions for running external commands.
:deprecated:
.. deprecated:: 2.6
The :mod:`commands` module has been removed in Python 3. Use the
:mod:`subprocess` module instead.
.. 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.
.. note::
In Python 3.x, :func:`getstatus` and two undocumented functions
(:func:`mk2arg` and :func:`mkarg`) have been removed. Also,
:func:`getstatusoutput` and :func:`getoutput` have been moved to the
:mod:`subprocess` 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 :c:func:`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.
.. function:: getstatus(file)
Return the output of ``ls -ld file`` as a string. This function uses the
:func:`getoutput` function, and properly escapes backslashes and dollar signs in
the argument.
.. deprecated:: 2.6
This function is nonobvious and useless. The name is also misleading in the
presence of :func:`getstatusoutput`.
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'
>>> commands.getstatus('/bin/ls')
'-rwxr-xr-x 1 root 13352 Oct 14 1994 /bin/ls'
.. seealso::
Module :mod:`subprocess`
Module for spawning and managing subprocesses.

141
Doc/library/compileall.rst Normal file
View File

@@ -0,0 +1,141 @@
:mod:`compileall` --- Byte-compile Python libraries
===================================================
.. module:: compileall
:synopsis: Tools for byte-compiling all Python source files in a directory tree.
**Source code:** :source:`Lib/compileall.py`
--------------
This module provides some utility functions to support installing Python
libraries. These functions compile Python source files in a directory tree.
This module can be used to create the cached byte-code files at library
installation time, which makes them available for use even by users who don't
have write permission to the library directories.
Command-line use
----------------
This module can work as a script (using :program:`python -m compileall`) to
compile Python sources.
.. program:: compileall
.. cmdoption:: directory ...
file ...
Positional arguments are files to compile or directories that contain
source files, traversed recursively. If no argument is given, behave as if
the command line was ``-l <directories from sys.path>``.
.. cmdoption:: -l
Do not recurse into subdirectories, only compile source code files directly
contained in the named or implied directories.
.. cmdoption:: -f
Force rebuild even if timestamps are up-to-date.
.. cmdoption:: -q
Do not print the list of files compiled, print only error messages.
.. cmdoption:: -d destdir
Directory prepended to the path to each file being compiled. This will
appear in compilation time tracebacks, and is also compiled in to the
byte-code file, where it will be used in tracebacks and other messages in
cases where the source file does not exist at the time the byte-code file is
executed.
.. cmdoption:: -x regex
regex is used to search the full path to each file considered for
compilation, and if the regex produces a match, the file is skipped.
.. cmdoption:: -i list
Read the file ``list`` and add each line that it contains to the list of
files and directories to compile. If ``list`` is ``-``, read lines from
``stdin``.
.. versionchanged:: 2.7
Added the ``-i`` option.
Public functions
----------------
.. 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 prepended to the path to each file being compiled
for use in compilation time tracebacks, and is also compiled in to the
byte-code file, where it will be used in tracebacks and other messages in
cases where the source file does not exist at the time the byte-code file is
executed.
If *force* is true, modules are re-compiled even if the timestamps are up to
date.
If *rx* is given, its search method is called on the complete path to each
file considered for compilation, and if it returns a true value, the file
is skipped.
If *quiet* is true, nothing is printed to the standard output unless errors
occur.
.. function:: compile_file(fullname[, ddir[, force[, rx[, quiet]]]])
Compile the file with path *fullname*.
If *ddir* is given, it is prepended to the path to the file being compiled
for use in compilation time tracebacks, and is also compiled in to the
byte-code file, where it will be used in tracebacks and other messages in
cases where the source file does not exist at the time the byte-code file is
executed.
If *rx* is given, its search method is passed the full path name to the
file being compiled, and if it returns a true value, the file is not
compiled and ``True`` is returned.
If *quiet* is true, nothing is printed to the standard output unless errors
occur.
.. versionadded:: 2.7
.. 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. All other parameters are passed to the :func:`compile_dir`
function. Note that unlike the other compile functions, ``maxlevels``
defaults to ``0``.
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(r'[/\\][.]svn'), force=True)
.. seealso::
Module :mod:`py_compile`
Byte-compile a single source file.

644
Doc/library/compiler.rst Normal file
View File

@@ -0,0 +1,644 @@
.. _compiler:
***********************
Python compiler package
***********************
.. deprecated:: 2.6
The :mod:`compiler` package has been removed in Python 3.
.. sectionauthor:: Jeremy Hylton <jeremy@zope.com>
The Python compiler package is a tool for analyzing Python source code and
generating Python bytecode. The compiler contains libraries to generate an
abstract syntax tree from Python source code and to generate Python
:term:`bytecode` from the tree.
The :mod:`compiler` package is a Python source to bytecode translator written in
Python. It uses the built-in parser and standard :mod:`parser` module to
generate a concrete syntax tree. This tree is used to generate an abstract
syntax tree (AST) and then Python bytecode.
The full functionality of the package duplicates the built-in compiler provided
with the Python interpreter. It is intended to match its behavior almost
exactly. Why implement another compiler that does the same thing? The package
is useful for a variety of purposes. It can be modified more easily than the
built-in compiler. The AST it generates is useful for analyzing Python source
code.
This chapter explains how the various components of the :mod:`compiler` package
work. It blends reference material with a tutorial.
The basic interface
===================
.. module:: compiler
:synopsis: Python code compiler written in Python.
:deprecated:
The top-level of the package defines four functions. If you import
:mod:`compiler`, you will get these functions and a collection of modules
contained in the package.
.. function:: parse(buf)
Returns an abstract syntax tree for the Python source code in *buf*. The
function raises :exc:`SyntaxError` if there is an error in the source code. The
return value is a :class:`compiler.ast.Module` instance that contains the tree.
.. function:: parseFile(path)
Return an abstract syntax tree for the Python source code in the file specified
by *path*. It is equivalent to ``parse(open(path).read())``.
.. function:: walk(ast, visitor[, verbose])
Do a pre-order walk over the abstract syntax tree *ast*. Call the appropriate
method on the *visitor* instance for each node encountered.
.. function:: compile(source, filename, mode, flags=None, dont_inherit=None)
Compile the string *source*, a Python module, statement or expression, into a
code object that can be executed by the exec statement or :func:`eval`. This
function is a replacement for the built-in :func:`compile` function.
The *filename* will be used for run-time error messages.
The *mode* must be 'exec' to compile a module, 'single' to compile a single
(interactive) statement, or 'eval' to compile an expression.
The *flags* and *dont_inherit* arguments affect future-related statements, but
are not supported yet.
.. function:: compileFile(source)
Compiles the file *source* and generates a .pyc file.
The :mod:`compiler` package contains the following modules: :mod:`ast`,
:mod:`consts`, :mod:`future`, :mod:`misc`, :mod:`pyassem`, :mod:`pycodegen`,
:mod:`symbols`, :mod:`transformer`, and :mod:`visitor`.
Limitations
===========
There are some problems with the error checking of the compiler package. The
interpreter detects syntax errors in two distinct phases. One set of errors is
detected by the interpreter's parser, the other set by the compiler. The
compiler package relies on the interpreter's parser, so it get the first phases
of error checking for free. It implements the second phase itself, and that
implementation is incomplete. For example, the compiler package does not raise
an error if a name appears more than once in an argument list: ``def f(x, x):
...``
A future version of the compiler should fix these problems.
Python Abstract Syntax
======================
The :mod:`compiler.ast` module defines an abstract syntax for Python. In the
abstract syntax tree, each node represents a syntactic construct. The root of
the tree is :class:`Module` object.
The abstract syntax offers a higher level interface to parsed Python source
code. The :mod:`parser` module and the compiler written in C for the Python
interpreter use a concrete syntax tree. The concrete syntax is tied closely to
the grammar description used for the Python parser. Instead of a single node
for a construct, there are often several levels of nested nodes that are
introduced by Python's precedence rules.
The abstract syntax tree is created by the :mod:`compiler.transformer` module.
The transformer relies on the built-in Python parser to generate a concrete
syntax tree. It generates an abstract syntax tree from the concrete tree.
.. index::
single: Stein, Greg
single: Tutt, Bill
The :mod:`transformer` module was created by Greg Stein and Bill Tutt for an
experimental Python-to-C compiler. The current version contains a number of
modifications and improvements, but the basic form of the abstract syntax and of
the transformer are due to Stein and Tutt.
AST Nodes
---------
.. module:: compiler.ast
The :mod:`compiler.ast` module is generated from a text file that describes each
node type and its elements. Each node type is represented as a class that
inherits from the abstract base class :class:`compiler.ast.Node` and defines a
set of named attributes for child nodes.
.. class:: Node()
The :class:`Node` instances are created automatically by the parser generator.
The recommended interface for specific :class:`Node` instances is to use the
public attributes to access child nodes. A public attribute may be bound to a
single node or to a sequence of nodes, depending on the :class:`Node` type. For
example, the :attr:`bases` attribute of the :class:`Class` node, is bound to a
list of base class nodes, and the :attr:`doc` attribute is bound to a single
node.
Each :class:`Node` instance has a :attr:`lineno` attribute which may be
``None``. XXX Not sure what the rules are for which nodes will have a useful
lineno.
All :class:`Node` objects offer the following methods:
.. method:: getChildren()
Returns a flattened list of the child nodes and objects in the order they
occur. Specifically, the order of the nodes is the order in which they
appear in the Python grammar. Not all of the children are :class:`Node`
instances. The names of functions and classes, for example, are plain
strings.
.. method:: getChildNodes()
Returns a flattened list of the child nodes in the order they occur. This
method is like :meth:`getChildren`, except that it only returns those
children that are :class:`Node` instances.
Two examples illustrate the general structure of :class:`Node` classes. The
:keyword:`while` statement is defined by the following grammar production::
while_stmt: "while" expression ":" suite
["else" ":" suite]
The :class:`While` node has three attributes: :attr:`test`, :attr:`body`, and
:attr:`else_`. (If the natural name for an attribute is also a Python reserved
word, it can't be used as an attribute name. An underscore is appended to the
word to make it a legal identifier, hence :attr:`else_` instead of
:keyword:`else`.)
The :keyword:`if` statement is more complicated because it can include several
tests. ::
if_stmt: 'if' test ':' suite ('elif' test ':' suite)* ['else' ':' suite]
The :class:`If` node only defines two attributes: :attr:`tests` and
:attr:`else_`. The :attr:`tests` attribute is a sequence of test expression,
consequent body pairs. There is one pair for each :keyword:`if`/:keyword:`elif`
clause. The first element of the pair is the test expression. The second
elements is a :class:`Stmt` node that contains the code to execute if the test
is true.
The :meth:`getChildren` method of :class:`If` returns a flat list of child
nodes. If there are three :keyword:`if`/:keyword:`elif` clauses and no
:keyword:`else` clause, then :meth:`getChildren` will return a list of six
elements: the first test expression, the first :class:`Stmt`, the second text
expression, etc.
The following table lists each of the :class:`Node` subclasses defined in
:mod:`compiler.ast` and each of the public attributes available on their
instances. The values of most of the attributes are themselves :class:`Node`
instances or sequences of instances. When the value is something other than an
instance, the type is noted in the comment. The attributes are listed in the
order in which they are returned by :meth:`getChildren` and
:meth:`getChildNodes`.
+-----------------------+--------------------+---------------------------------+
| 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:`Backquote` | :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` | |
+-----------------------+--------------------+---------------------------------+
Assignment nodes
----------------
There is a collection of nodes used to represent assignments. Each assignment
statement in the source code becomes a single :class:`Assign` node in the AST.
The :attr:`nodes` attribute is a list that contains a node for each assignment
target. This is necessary because assignment can be chained, e.g. ``a = b =
2``. Each :class:`Node` in the list will be one of the following classes:
:class:`AssAttr`, :class:`AssList`, :class:`AssName`, or :class:`AssTuple`.
Each target assignment node will describe the kind of object being assigned to:
:class:`AssName` for a simple name, e.g. ``a = 1``. :class:`AssAttr` for an
attribute assigned, e.g. ``a.x = 1``. :class:`AssList` and :class:`AssTuple` for
list and tuple expansion respectively, e.g. ``a, b, c = a_tuple``.
The target assignment nodes also have a :attr:`flags` attribute that indicates
whether the node is being used for assignment or in a delete statement. The
:class:`AssName` is also used to represent a delete statement, e.g. :class:`del
x`.
When an expression contains several attribute references, an assignment or
delete statement will contain only one :class:`AssAttr` node -- for the final
attribute reference. The other attribute references will be represented as
:class:`Getattr` nodes in the :attr:`expr` attribute of the :class:`AssAttr`
instance.
Examples
--------
This section shows several simple examples of ASTs for Python source code. The
examples demonstrate how to use the :func:`parse` function, what the repr of an
AST looks like, and how to access attributes of an AST node.
The first module defines a single function. Assume it is stored in
:file:`doublelib.py`. ::
"""This is an example module.
This is the docstring.
"""
def double(x):
"Return twice the argument"
return x * 2
In the interactive interpreter session below, I have reformatted the long AST
reprs for readability. The AST reprs use unqualified class names. If you want
to create an instance from a repr, you must import the class names from the
:mod:`compiler.ast` module. ::
>>> import compiler
>>> mod = compiler.parseFile("doublelib.py")
>>> mod
Module('This is an example module.\n\nThis is the docstring.\n',
Stmt([Function(None, 'double', ['x'], [], 0,
'Return twice the argument',
Stmt([Return(Mul((Name('x'), Const(2))))]))]))
>>> from compiler.ast import *
>>> Module('This is an example module.\n\nThis is the docstring.\n',
... Stmt([Function(None, 'double', ['x'], [], 0,
... 'Return twice the argument',
... Stmt([Return(Mul((Name('x'), Const(2))))]))]))
Module('This is an example module.\n\nThis is the docstring.\n',
Stmt([Function(None, 'double', ['x'], [], 0,
'Return twice the argument',
Stmt([Return(Mul((Name('x'), Const(2))))]))]))
>>> mod.doc
'This is an example module.\n\nThis is the docstring.\n'
>>> for node in mod.node.nodes:
... print node
...
Function(None, 'double', ['x'], [], 0, 'Return twice the argument',
Stmt([Return(Mul((Name('x'), Const(2))))]))
>>> func = mod.node.nodes[0]
>>> func.code
Stmt([Return(Mul((Name('x'), Const(2))))])
Using Visitors to Walk ASTs
===========================
.. module:: compiler.visitor
The visitor pattern is ... The :mod:`compiler` package uses a variant on the
visitor pattern that takes advantage of Python's introspection features to
eliminate the need for much of the visitor's infrastructure.
The classes being visited do not need to be programmed to accept visitors. The
visitor need only define visit methods for classes it is specifically interested
in; a default visit method can handle the rest.
XXX The magic :meth:`visit` method for visitors.
.. function:: walk(tree, visitor[, verbose])
.. class:: ASTVisitor()
The :class:`ASTVisitor` is responsible for walking over the tree in the correct
order. A walk begins with a call to :meth:`preorder`. For each node, it checks
the *visitor* argument to :meth:`preorder` for a method named 'visitNodeType,'
where NodeType is the name of the node's class, e.g. for a :class:`While` node a
:meth:`visitWhile` would be called. If the method exists, it is called with the
node as its first argument.
The visitor method for a particular node type can control how child nodes are
visited during the walk. The :class:`ASTVisitor` modifies the visitor argument
by adding a visit method to the visitor; this method can be used to visit a
particular child node. If no visitor is found for a particular node type, the
:meth:`default` method is called.
:class:`ASTVisitor` objects have the following methods:
XXX describe extra arguments
.. method:: default(node[, ...])
.. method:: dispatch(node[, ...])
.. method:: preorder(tree, visitor)
Bytecode Generation
===================
The code generator is a visitor that emits bytecodes. Each visit method can
call the :meth:`emit` method to emit a new bytecode. The basic code generator
is specialized for modules, classes, and functions. An assembler converts that
emitted instructions to the low-level bytecode format. It handles things like
generation of constant lists of code objects and calculation of jump offsets.

559
Doc/library/configparser.rst Normal file
View File

@@ -0,0 +1,559 @@
: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>
.. note::
The :mod:`ConfigParser` module has been renamed to :mod:`configparser` in
Python 3. The :term:`2to3` tool will automatically adapt imports when
converting your sources to Python 3.
.. index::
pair: .ini; file
pair: configuration; file
single: ini file
single: Windows ini file
This module defines the class :class:`~ConfigParser.ConfigParser`. The :class:`~ConfigParser.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.
.. note::
This library does *not* interpret or write the value-type prefixes used in
the Windows Registry extended version of INI syntax.
.. seealso::
Module :mod:`shlex`
Support for creating Unix shell-like mini-languages which can be used as
an alternate format for application configuration files.
Module :mod:`json`
The json module implements a subset of JavaScript syntax which can also
be used for this purpose.
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` (see section 3.1.1, "LONG HEADER FIELDS"); ``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.
Configuration files may include comments, prefixed by specific characters (``#``
and ``;``). Comments may appear on their own in an otherwise empty line, or may
be entered in lines holding values or section names. In the latter case, they
need to be preceded by a whitespace character to be recognized as a comment.
(For backwards compatibility, only ``;`` starts an inline comment, while ``#``
does not.)
On top of the core functionality, :class:`SafeConfigParser` supports
interpolation. This means 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.
For example::
[My Section]
foodir: %(dir)s/whatever
dir=frob
long: this value continues
in the next line
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.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 built-in dictionary. An alternative dictionary
type can be passed to the :class:`~ConfigParser.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[, allow_no_value]]])
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. When *allow_no_value*
is true (default: ``False``), options without values are accepted; the value
presented for these is ``None``.
This class does not
support the magical interpolation behavior.
All option names are passed through the :meth:`optionxform` method. Its
default implementation converts option names to lower case.
.. versionadded:: 2.3
.. versionchanged:: 2.6
*dict_type* was added.
.. versionchanged:: 2.7
The default *dict_type* is :class:`collections.OrderedDict`.
*allow_no_value* was added.
.. class:: ConfigParser([defaults[, dict_type[, allow_no_value]]])
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. Using
the default implementation of :meth:`optionxform`, the values ``foo %(bar)s``
and ``foo %(BAR)s`` are equivalent.
.. versionadded:: 2.3
.. versionchanged:: 2.6
*dict_type* was added.
.. versionchanged:: 2.7
The default *dict_type* is :class:`collections.OrderedDict`.
*allow_no_value* was added.
.. class:: SafeConfigParser([defaults[, dict_type[, allow_no_value]]])
Derived class of :class:`~ConfigParser.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
.. versionchanged:: 2.6
*dict_type* was added.
.. versionchanged:: 2.7
The default *dict_type* is :class:`collections.OrderedDict`.
*allow_no_value* was added.
.. exception:: Error
Base class for all other configparser exceptions.
.. 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.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. If the name
``DEFAULT`` (or any of it's case-insensitive variants) is passed,
:exc:`ValueError` 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.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.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.
You don't necessarily need to subclass a ConfigParser to use this method, you
can also re-set it on an instance, to a function that takes a string
argument. Setting it to ``str``, for example, would make option names case
sensitive::
cfgparser = ConfigParser()
...
cfgparser.optionxform = str
Note that when reading configuration files, whitespace around the
option names are stripped before :meth:`optionxform` is called.
.. _configparser-objects:
ConfigParser Objects
--------------------
The :class:`~ConfigParser.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*. If *vars* is provided, it
must be a dictionary. The *option* is looked up in *vars* (if provided),
*section*, and in *defaults* in that order.
All the ``'%'`` interpolations are expanded in the return values, unless the
*raw* argument is true. Values for interpolation keys are looked up in the
same manner as the option.
.. 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.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
Examples
--------
An example of writing to a configuration file::
import ConfigParser
config = ConfigParser.RawConfigParser()
# When adding sections or items, add them in the reverse order of
# how you want them to be displayed in the actual file.
# In addition, please note that using RawConfigParser's and the raw
# mode of ConfigParser's respective set functions, you can assign
# non-string values to keys internally, but will receive an error
# when attempting to write to a file or when you get it in non-raw
# mode. SafeConfigParser does not allow such assignments to take place.
config.add_section('Section1')
config.set('Section1', 'an_int', '15')
config.set('Section1', 'a_bool', 'true')
config.set('Section1', 'a_float', '3.1415')
config.set('Section1', 'baz', 'fun')
config.set('Section1', 'bar', 'Python')
config.set('Section1', 'foo', '%(bar)s is %(baz)s!')
# Writing our configuration file to 'example.cfg'
with open('example.cfg', 'wb') as configfile:
config.write(configfile)
An example of reading the configuration file again::
import ConfigParser
config = ConfigParser.RawConfigParser()
config.read('example.cfg')
# getfloat() raises an exception if the value is not a float
# getint() and getboolean() also do this for their respective types
a_float = config.getfloat('Section1', 'a_float')
an_int = config.getint('Section1', 'an_int')
print a_float + an_int
# Notice that the next output does not interpolate '%(bar)s' or '%(baz)s'.
# This is because we are using a RawConfigParser().
if config.getboolean('Section1', 'a_bool'):
print config.get('Section1', 'foo')
To get interpolation, you will need to use a :class:`~ConfigParser.ConfigParser` or
:class:`SafeConfigParser`::
import ConfigParser
config = ConfigParser.ConfigParser()
config.read('example.cfg')
# Set the third, optional argument of get to 1 if you wish to use raw mode.
print config.get('Section1', 'foo', 0) # -> "Python is fun!"
print config.get('Section1', 'foo', 1) # -> "%(bar)s is %(baz)s!"
# The optional fourth argument is a dict with members that will take
# precedence in interpolation.
print config.get('Section1', 'foo', 0, {'bar': 'Documentation',
'baz': 'evil'})
Defaults are available in all three types of ConfigParsers. They are used in
interpolation if an option used is not defined elsewhere. ::
import ConfigParser
# New instance with 'bar' and 'baz' defaulting to 'Life' and 'hard' each
config = ConfigParser.SafeConfigParser({'bar': 'Life', 'baz': 'hard'})
config.read('example.cfg')
print config.get('Section1', 'foo') # -> "Python is fun!"
config.remove_option('Section1', 'bar')
config.remove_option('Section1', 'baz')
print config.get('Section1', 'foo') # -> "Life is hard!"
The function ``opt_move`` below can be used to move options between sections::
def opt_move(config, section1, section2, option):
try:
config.set(section2, option, config.get(section1, option, 1))
except ConfigParser.NoSectionError:
# Create non-existent section
config.add_section(section2)
opt_move(config, section1, section2, option)
else:
config.remove_option(section1, option)
Some configuration files are known to include settings without values, but which
otherwise conform to the syntax supported by :mod:`ConfigParser`. The
*allow_no_value* parameter to the constructor can be used to indicate that such
values should be accepted:
.. doctest::
>>> import ConfigParser
>>> import io
>>> sample_config = """
... [mysqld]
... user = mysql
... pid-file = /var/run/mysqld/mysqld.pid
... skip-external-locking
... old_passwords = 1
... skip-bdb
... skip-innodb
... """
>>> config = ConfigParser.RawConfigParser(allow_no_value=True)
>>> config.readfp(io.BytesIO(sample_config))
>>> # Settings with values are treated as before:
>>> config.get("mysqld", "user")
'mysql'
>>> # Settings without values provide None:
>>> config.get("mysqld", "skip-bdb")
>>> # Settings which aren't specified still raise an error:
>>> config.get("mysqld", "does-not-exist")
Traceback (most recent call last):
...
ConfigParser.NoOptionError: No option 'does-not-exist' in section: 'mysqld'

85
Doc/library/constants.rst Normal file
View File

@@ -0,0 +1,85 @@
.. _built-in-consts:
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.
.. versionchanged:: 2.4
Assignments to ``None`` are illegal and raise a :exc:`SyntaxError`.
.. 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
Special value used in conjunction with extended slicing syntax.
.. data:: __debug__
This constant is true if Python was not started with an :option:`-O` option.
See also the :keyword:`assert` statement.
.. note::
The names :data:`None` and :data:`__debug__` cannot be reassigned
(assignments to them, even as an attribute name, raise :exc:`SyntaxError`),
so they can be considered "true" constants.
.. versionchanged:: 2.7
Assignments to ``__debug__`` as an attribute became illegal.
Constants added by the :mod:`site` module
-----------------------------------------
The :mod:`site` module (which is imported automatically during startup, except
if the :option:`-S` command-line option is given) adds several constants to the
built-in namespace. They are useful for the interactive interpreter shell and
should not be used in programs.
.. data:: quit([code=None])
exit([code=None])
Objects that when printed, print a message like "Use quit() or Ctrl-D
(i.e. EOF) to exit", and when called, raise :exc:`SystemExit` with the
specified exit code.
.. data:: copyright
credits
Objects that when printed or called, print the text of copyright or
credits, respectively.
.. data:: license
Object that when printed, prints the message "Type license() to see the
full license text", and when called, displays the full license text in a
pager-like fashion (one screen at a time).

147
Doc/library/contextlib.rst Normal file
View File

@@ -0,0 +1,147 @@
:mod:`contextlib` --- Utilities for :keyword:`with`\ -statement contexts
========================================================================
.. module:: contextlib
:synopsis: Utilities for with-statement contexts.
.. versionadded:: 2.5
**Source code:** :source:`Lib/contextlib.py`
--------------
This module provides utilities for common tasks involving the :keyword:`with`
statement. For more information see also :ref:`typecontextmanager` and
:ref:`context-managers`.
Functions provided:
.. function:: contextmanager(func)
This function is a :term:`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.
While many objects natively support use in with statements, sometimes a
resource needs to be managed that isn't a context manager in its own right,
and doesn't implement a ``close()`` method for use with ``contextlib.closing``
An abstract example would be the following to ensure correct resource
management::
from contextlib import contextmanager
@contextmanager
def managed_resource(*args, **kwds):
# Code to acquire resource, e.g.:
resource = acquire_resource(*args, **kwds)
try:
yield resource
finally:
# Code to release resource, e.g.:
release_resource(resource)
>>> with managed_resource(timeout=3600) as resource:
... # Resource is released at the end of this block,
... # even if code in the block raises an exception
The function being decorated must return a :term:`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.
This function has been deprecated in favour of the multiple manager form
of the :keyword:`with` statement.
The one advantage of this function over the multiple manager form of the
:keyword:`with` statement is that argument unpacking allows it to be
used with a variable number of context managers as follows::
from contextlib import nested
with nested(*managers):
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.
This function has two major quirks that have led to it being deprecated. Firstly,
as the context managers are all constructed before the function is invoked, the
:meth:`__new__` and :meth:`__init__` methods of the inner context managers are
not actually covered by the scope of the outer context managers. That means, for
example, that using :func:`nested` to open two files is a programming error as the
first file will not be closed promptly if an exception is thrown when opening
the second file.
Secondly, if the :meth:`__enter__` method of one of the inner context managers
raises an exception that is caught and suppressed by the :meth:`__exit__` method
of one of the outer context managers, this construct will raise
:exc:`RuntimeError` rather than skipping the body of the :keyword:`with`
statement.
Developers that need to support nesting of a variable number of context managers
can either use the :mod:`warnings` module to suppress the DeprecationWarning
raised by this function or else use this function as a model for an application
specific implementation.
.. deprecated:: 2.7
The with-statement now supports this functionality directly (without the
confusing error prone quirks).
.. 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 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:`343` - The "with" statement
The specification, background, and examples for the Python :keyword:`with`
statement.

311
Doc/library/cookie.rst Normal file
View File

@@ -0,0 +1,311 @@
: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>
.. note::
The :mod:`Cookie` module has been renamed to :mod:`http.cookies` in Python
3. The :term:`2to3` tool will automatically adapt imports when converting
your sources to Python 3.
**Source code:** :source:`Lib/Cookie.py`
--------------
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 and also
many current day browsers and servers have relaxed parsing rules when comes to
Cookie handling. As a result, the parsing rules used are a bit less strict.
The character set, :data:`string.ascii_letters`, :data:`string.digits` and
``!#$%&'*+-.^_`|~`` denote the set of valid characters allowed by this module
in Cookie name (as :attr:`~Morsel.key`).
.. note::
On encountering an invalid cookie, :exc:`CookieError` is raised, so if your
cookie data comes from a browser you should always prepare for invalid data
and catch :exc:`CookieError` on parsing.
.. 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.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.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``
* ``httponly``
The attribute :attr:`httponly` specifies that the cookie is only transferred
in HTTP requests, and is not accessible through JavaScript. This is intended
to mitigate some forms of cross-site scripting.
The keys are case-insensitive.
.. versionadded:: 2.6
The :attr:`httponly` attribute was added.
.. 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* attributes.
.. 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.
.. doctest::
:options: +NORMALIZE_WHITESPACE
>>> import Cookie
>>> C = Cookie.SimpleCookie()
>>> C["fig"] = "newton"
>>> C["sugar"] = "wafer"
>>> print C # generate HTTP headers
Set-Cookie: fig=newton
Set-Cookie: sugar=wafer
>>> print C.output() # same thing
Set-Cookie: fig=newton
Set-Cookie: sugar=wafer
>>> C = Cookie.SimpleCookie()
>>> 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.SimpleCookie()
>>> C.load("chips=ahoy; vienna=finger") # load from a string (HTTP header)
>>> print C
Set-Cookie: chips=ahoy
Set-Cookie: vienna=finger
>>> C = Cookie.SimpleCookie()
>>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";')
>>> print C
Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;"
>>> C = Cookie.SimpleCookie()
>>> C["oreo"] = "doublestuff"
>>> C["oreo"]["path"] = "/"
>>> print C
Set-Cookie: oreo=doublestuff; Path=/
>>> 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
>>> # SerialCookie and SmartCookie are deprecated
>>> # using it can cause security loopholes in your code.
>>> 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

771
Doc/library/cookielib.rst Normal file
View File

@@ -0,0 +1,771 @@
:mod:`cookielib` --- Cookie handling for HTTP clients
=====================================================
.. module:: cookielib
:synopsis: Classes for automatic handling of HTTP cookies.
.. moduleauthor:: John J. Lee <jjl@pobox.com>
.. sectionauthor:: John J. Lee <jjl@pobox.com>
.. note::
The :mod:`cookielib` module has been renamed to :mod:`http.cookiejar` in
Python 3. The :term:`2to3` tool will automatically adapt imports when
converting your sources to Python 3.
.. versionadded:: 2.4
**Source code:** :source:`Lib/cookielib.py`
--------------
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:`~cookielib.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:`~cookielib.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.
https://curl.haxx.se/rfc/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 :term:`iterator` protocol for iterating over
contained :class:`~cookielib.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:`~cookielib.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:`~cookielib.Cookie` if policy says it's OK to do so.
.. method:: CookieJar.set_cookie(cookie)
Set a :class:`~cookielib.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.
.. 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::
Version 3 of the Firefox web browser no longer writes cookies in the
``cookies.txt`` file format.
.. 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:`~cookielib.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:`~cookielib.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``.
.. _cookielib-cookie-objects:
Cookie Objects
--------------
:class:`~cookielib.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:`~cookielib.Cookie` class also defines the following method:
.. method:: Cookie.is_expired([now=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.path.expanduser("~"), ".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=DefaultCookiePolicy.DomainStrict,
blocked_domains=["ads.net", ".ads.net"])
cj = CookieJar(policy)
opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")

94
Doc/library/copy.rst Normal file
View File

@@ -0,0 +1,94 @@
:mod:`copy` --- Shallow and deep copy operations
================================================
.. module:: copy
:synopsis: Shallow and deep copy operations.
Assignment statements in Python do not copy objects, they create bindings
between a target and an object. For collections that are mutable or contain
mutable items, a copy is sometimes needed so one can change one copy without
changing the other. This module provides generic shallow and deep copy
operations (explained below).
Interface summary:
.. function:: copy(x)
Return a shallow copy of *x*.
.. function:: deepcopy(x)
Return a deep copy of *x*.
.. exception:: error
Raised for module specific errors.
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, such as data
which is intended to be shared 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.
Shallow copies of dictionaries can be made using :meth:`dict.copy`, and
of lists by assigning a slice of the entire list, for example,
``copied_list = original_list[:]``.
.. 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.

66
Doc/library/copy_reg.rst Normal file
View File

@@ -0,0 +1,66 @@
:mod:`copy_reg` --- Register :mod:`pickle` support functions
============================================================
.. module:: copy_reg
:synopsis: Register pickle support functions.
.. note::
The :mod:`copy_reg` module has been renamed to :mod:`copyreg` in Python 3.
The :term:`2to3` tool will automatically adapt imports when converting your
sources to Python 3.
.. index::
module: pickle
module: cPickle
module: copy
The :mod:`copy_reg` module offers a way to define functions used while pickling
specific objects. The :mod:`pickle`, :mod:`cPickle`, and :mod:`copy` modules
use those functions when pickling/copying those objects. The module 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*.
Example
-------
The example below would like to show how to register a pickle function and how
it will be used:
>>> import copy_reg, copy, pickle
>>> class C(object):
... def __init__(self, a):
... self.a = a
...
>>> def pickle_c(c):
... print("pickling a C instance...")
... return C, (c.a,)
...
>>> copy_reg.pickle(C, pickle_c)
>>> c = C(1)
>>> d = copy.copy(c)
pickling a C instance...
>>> p = pickle.dumps(c)
pickling a C instance...

61
Doc/library/crypt.rst Normal file
View File

@@ -0,0 +1,61 @@
: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 login():
username = raw_input('Python login:')
cryptedpasswd = pwd.getpwnam(username)[1]
if cryptedpasswd:
if cryptedpasswd == 'x' or cryptedpasswd == '*':
raise NotImplementedError(
"Sorry, currently no support for shadow passwords")
cleartext = getpass.getpass()
return crypt.crypt(cleartext, cryptedpasswd) == cryptedpasswd
else:
return 1

20
Doc/library/crypto.rst Normal file
View File

@@ -0,0 +1,20 @@
.. _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
md5.rst
sha.rst

622
Doc/library/csv.rst Normal file
View File

@@ -0,0 +1,622 @@
: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`.
.. seealso::
: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', **fmtparams)
Return a reader object which will iterate over lines in the given *csvfile*.
*csvfile* can be any object which supports the :term:`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 *fmtparams* 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`.
Each row read from the csv file is returned as a list of strings. No
automatic data type conversion is performed.
A short usage example::
>>> import csv
>>> with open('eggs.csv', 'rb') as csvfile:
... spamreader = csv.reader(csvfile, delimiter=' ', quotechar='|')
... for row in spamreader:
... print ', '.join(row)
Spam, Spam, Spam, Spam, Spam, Baked Beans
Spam, Lovely Spam, Wonderful Spam
.. 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', **fmtparams)
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 *fmtparams* 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`. 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.
Floats are stringified with :func:`repr` before being written.
All other non-string data are stringified with :func:`str` before being written.
A short usage example::
import csv
with open('eggs.csv', 'wb') as csvfile:
spamwriter = csv.writer(csvfile, delimiter=' ',
quotechar='|', quoting=csv.QUOTE_MINIMAL)
spamwriter.writerow(['Spam'] * 5 + ['Baked Beans'])
spamwriter.writerow(['Spam', 'Lovely Spam', 'Wonderful Spam'])
.. function:: register_dialect(name[, dialect], **fmtparams)
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 *fmtparams* 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`.
.. 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.
.. versionchanged:: 2.5
This function now returns an immutable :class:`Dialect`. Previously an
instance of the requested dialect was returned. Users could modify the
underlying class, changing the behavior of active readers and writers.
.. 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(f, fieldnames=None, restkey=None, restval=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. The *fieldnames* parameter is a :ref:`sequence
<collections-abstract-base-classes>` whose elements are associated with the
fields of the input data in order. These elements become the keys of the
resulting dictionary. If the *fieldnames* parameter is omitted, the values
in the first row of the file *f* will be used as the fieldnames. 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.
A short usage example::
>>> import csv
>>> with open('names.csv') as csvfile:
... reader = csv.DictReader(csvfile)
... for row in reader:
... print(row['first_name'], row['last_name'])
...
Baked Beans
Lovely Spam
Wonderful Spam
.. class:: DictWriter(f, 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 is a :ref:`sequence
<collections-abstract-base-classes>` of keys that identify the order in
which values in the dictionary passed to the :meth:`writerow` method are
written to the file *f*. 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 file *f*.
A short usage example::
import csv
with open('names.csv', 'w') as csvfile:
fieldnames = ['first_name', 'last_name']
writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
writer.writeheader()
writer.writerow({'first_name': 'Baked', 'last_name': 'Beans'})
writer.writerow({'first_name': 'Lovely', 'last_name': 'Spam'})
writer.writerow({'first_name': 'Wonderful', 'last_name': 'Spam'})
.. 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:: 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:: 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.
An example for :class:`Sniffer` use::
with open('example.csv', 'rb') as csvfile:
dialect = csv.Sniffer().sniff(csvfile.read(1024))
csvfile.seek(0)
reader = csv.reader(csvfile, dialect)
# ... process CSV file contents here ...
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
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`.
.. attribute:: Dialect.strict
When ``True``, raise exception :exc:`Error` on bad CSV input.
The default is ``False``.
Reader Objects
--------------
Reader objects (:class:`DictReader` instances and objects returned by the
:func:`reader` function) have the following public methods:
.. method:: csvreader.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:: csvreader.dialect
A read-only description of the dialect in use by the parser.
.. attribute:: csvreader.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
DictReader objects have the following public attribute:
.. attribute:: csvreader.fieldnames
If not passed as a parameter when creating the object, this attribute is
initialized upon first access or when the first record is read from the
file.
.. versionchanged:: 2.6
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:: csvwriter.writerow(row)
Write the *row* parameter to the writer's file object, formatted according to
the current dialect.
.. method:: csvwriter.writerows(rows)
Write all elements in *rows* (an iterable 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:: csvwriter.dialect
A read-only description of the dialect in use by the writer.
DictWriter objects have the following public method:
.. method:: DictWriter.writeheader()
Write a row with the field names (as specified in the constructor).
.. versionadded:: 2.7
.. _csv-examples:
Examples
--------
The simplest example of reading a CSV file::
import csv
with open('some.csv', 'rb') as f:
reader = csv.reader(f)
for row in reader:
print row
Reading a file with an alternate format::
import csv
with open('passwd', 'rb') as f:
reader = csv.reader(f, delimiter=':', quoting=csv.QUOTE_NONE)
for row in reader:
print row
The corresponding simplest possible writing example is::
import csv
with open('some.csv', 'wb') as f:
writer = csv.writer(f)
writer.writerows(someiterable)
Registering a new dialect::
import csv
csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)
with open('passwd', 'rb') as f:
reader = csv.reader(f, 'unixpwd')
A slightly more advanced use of the reader --- catching and reporting errors::
import csv, sys
filename = 'some.csv'
with open(filename, 'rb') as f:
reader = csv.reader(f)
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 :term:`generator` that wraps :class:`csv.reader`
to handle Unicode CSV data (a list of Unicode strings). :func:`utf_8_encoder`
is a :term:`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 self.reader.next().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 = self.reader.next()
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)

2568
Doc/library/ctypes.rst Normal file
View File

File diff suppressed because it is too large Load Diff

228
Doc/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; space or horizontal tab.
.. function:: iscntrl(c)
Checks for an ASCII control character (in the range 0x00 to 0x1f or 0x7f).
.. 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.

118
Doc/library/curses.panel.rst Normal file
View File

@@ -0,0 +1,118 @@
: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.

1788
Doc/library/curses.rst Normal file
View File

File diff suppressed because it is too large Load Diff

20
Doc/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

39
Doc/library/datatypes.rst Normal file
View File

@@ -0,0 +1,39 @@
.. _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.
Python also provides some built-in data types, in particular,
:class:`dict`, :class:`list`, :class:`set` (which along with
:class:`frozenset`, replaces the deprecated :mod:`sets` module), and
:class:`tuple`. The :class:`str` class can be used to handle binary data
and 8-bit text, and the :class:`unicode` class to handle Unicode text.
The following modules are documented in this chapter:
.. toctree::
datetime.rst
calendar.rst
collections.rst
heapq.rst
bisect.rst
array.rst
sets.rst
sched.rst
mutex.rst
queue.rst
weakref.rst
userdict.rst
types.rst
new.rst
copy.rst
pprint.rst
repr.rst

1780
Doc/library/datetime.rst Normal file
View File

File diff suppressed because it is too large Load Diff

115
Doc/library/dbhash.rst Normal file
View File

@@ -0,0 +1,115 @@
: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>
.. deprecated:: 2.6
The :mod:`dbhash` module has been removed in Python 3.
.. 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:
+---------+-------------------------------------------+
| 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 |
+---------+-------------------------------------------+
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 xrange(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.

86
Doc/library/dbm.rst Normal file
View File

@@ -0,0 +1,86 @@
:mod:`dbm` --- Simple "database" interface
==========================================
.. module:: dbm
:platform: Unix
:synopsis: The standard "database" interface, based on ndbm.
.. note::
The :mod:`dbm` module has been renamed to :mod:`dbm.ndbm` in Python 3. The
:term:`2to3` tool will automatically adapt imports when converting your
sources to Python 3.
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`` (and will be
modified by the prevailing umask).
In addition to the dictionary-like methods, ``dbm`` objects
provide the following method:
.. function:: close()
Close the ``dbm`` database.
.. 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.

17
Doc/library/debug.rst Normal file
View File

@@ -0,0 +1,17 @@
***********************
Debugging and Profiling
***********************
These libraries help you with Python development: the debugger enables you to
step through code, analyze stack frames and set breakpoints etc., and the
profilers run code and give you a detailed breakdown of execution times,
allowing you to identify bottlenecks in your programs.
.. toctree::
bdb.rst
pdb.rst
profile.rst
hotshot.rst
timeit.rst
trace.rst

2054
Doc/library/decimal.rst Normal file
View File

File diff suppressed because it is too large Load Diff

24
Doc/library/development.rst Normal file
View File

@@ -0,0 +1,24 @@
.. _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. :program:`2to3` can translate Python 2.x
source code into valid Python 3.x code.
The list of modules described in this chapter is:
.. toctree::
pydoc.rst
doctest.rst
unittest.rst
2to3.rst
test.rst

783
Doc/library/difflib.rst Normal file
View File

@@ -0,0 +1,783 @@
: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>
.. Markup by Fred L. Drake, Jr. <fdrake@acm.org>
.. testsetup::
import sys
from difflib import *
.. versionadded:: 2.1
This module provides classes and functions for comparing sequences. It
can be used for example, for comparing files, and can produce difference
information in various formats, including HTML and context and unified
diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
.. class:: SequenceMatcher
This is a flexible class for comparing pairs of sequences of any type, so long
as the sequence elements are :term:`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.
**Automatic junk heuristic:** :class:`SequenceMatcher` supports a heuristic that
automatically treats certain sequence items as junk. The heuristic counts how many
times each individual item appears in the sequence. If an item's duplicates (after
the first one) account for more than 1% of the sequence and the sequence is at least
200 items long, this item is marked as "popular" and is treated as junk for
the purpose of sequence matching. This heuristic can be turned off by setting
the ``autojunk`` argument to ``False`` when creating the :class:`SequenceMatcher`.
.. versionadded:: 2.7.1
The *autojunk* parameter.
.. 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=8, wrapcolumn=None, linejunk=None, charjunk=IS_CHARACTER_JUNK)
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 :func:`ndiff`
(used by :class:`HtmlDiff` to generate the side by side HTML differences). See
:func:`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 :term:`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 ISO 8601 format. If not specified, the
strings default to blanks.
>>> s1 = ['bacon\n', 'eggs\n', 'ham\n', 'guido\n']
>>> s2 = ['python\n', 'eggy\n', 'hamster\n', 'guido\n']
>>> for line in context_diff(s1, s2, fromfile='before.py', tofile='after.py'):
... sys.stdout.write(line) # doctest: +NORMALIZE_WHITESPACE
*** before.py
--- after.py
***************
*** 1,4 ****
! bacon
! eggs
! ham
guido
--- 1,4 ----
! python
! eggy
! hamster
guido
See :ref:`difflib-interface` for a more detailed example.
.. 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 :term:`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 :term:`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 an 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 ISO 8601 format. If not specified, the
strings default to blanks.
>>> s1 = ['bacon\n', 'eggs\n', 'ham\n', 'guido\n']
>>> s2 = ['python\n', 'eggy\n', 'hamster\n', 'guido\n']
>>> for line in unified_diff(s1, s2, fromfile='before.py', tofile='after.py'):
... sys.stdout.write(line) # doctest: +NORMALIZE_WHITESPACE
--- before.py
+++ after.py
@@ -1,4 +1,4 @@
-bacon
-eggs
-ham
+python
+eggy
+hamster
guido
See :ref:`difflib-interface` for a more detailed example.
.. 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.drdobbs.com/database/pattern-matching-the-gestalt-approach/184407970>`_
Discussion of a similar algorithm by John W. Ratcliff and D. E. Metzener. This
was published in `Dr. Dobb's Journal <http://www.drdobbs.com/>`_ in July, 1988.
.. _sequence-matcher:
SequenceMatcher Objects
-----------------------
The :class:`SequenceMatcher` class has this constructor:
.. class:: SequenceMatcher(isjunk=None, a='', b='', autojunk=True)
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 :term:`hashable`.
The optional argument *autojunk* can be used to disable the automatic junk
heuristic.
.. versionadded:: 2.7.1
The *autojunk* parameter.
:class:`SequenceMatcher` objects have the following methods:
.. method:: 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:: set_seq1(a)
Set the first sequence to be compared. The second sequence to be compared
is not changed.
.. method:: set_seq2(b)
Set the second sequence to be compared. The first sequence to be compared
is not changed.
.. method:: 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:`find_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)
Match(a=0, b=4, size=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)
Match(a=1, b=0, size=4)
If no blocks match, this returns ``(alo, blo, 0)``.
.. versionchanged:: 2.6
This method returns a :term:`named tuple` ``Match(a, b, size)``.
.. method:: get_matching_blocks()
Return list of triples describing non-overlapping 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.
.. XXX Explain why a dummy is used!
.. versionchanged:: 2.5
The guarantee that adjacent triples always describe non-adjacent blocks
was implemented.
.. doctest::
>>> s = SequenceMatcher(None, "abxcd", "abcd")
>>> s.get_matching_blocks()
[Match(a=0, b=0, size=2), Match(a=3, b=2, size=2), Match(a=5, b=4, size=0)]
.. method:: 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:: get_grouped_opcodes([n])
Return a :term:`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:: 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:: quick_ratio()
Return an upper bound on :meth:`ratio` relatively quickly.
.. method:: real_quick_ratio()
Return an upper bound on :meth:`ratio` very quickly.
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 21 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:29] b[17:38]
.. seealso::
* The :func:`get_close_matches` function in this module which shows how
simple code building on :class:`SequenceMatcher` can be used to do useful
work.
* `Simple version control recipe
<https://code.activestate.com/recipes/576729/>`_ for a small application
built with :class:`SequenceMatcher`.
.. _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:`~file.readlines` method of file-like objects. The delta
generated also consists of newline-terminated strings, ready to be
printed as-is via the :meth:`~file.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:`~file.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.
.. _difflib-interface:
A command-line interface to difflib
-----------------------------------
This example shows how to use difflib to create a ``diff``-like utility.
It is also contained in the Python source distribution, as
:file:`Tools/scripts/diff.py`.
.. testcode::
""" Command line interface to difflib.py providing diffs in four formats:
* ndiff: lists every line and highlights interline changes.
* context: highlights clusters of changes in a before/after format.
* unified: highlights clusters of changes in an inline format.
* html: generates side by side comparison with change highlights.
"""
import sys, os, time, difflib, optparse
def main():
# Configure the option parser
usage = "usage: %prog [options] fromfile tofile"
parser = optparse.OptionParser(usage)
parser.add_option("-c", action="store_true", default=False,
help='Produce a context format diff (default)')
parser.add_option("-u", action="store_true", default=False,
help='Produce a unified format diff')
hlp = 'Produce HTML side by side diff (can use -c and -l in conjunction)'
parser.add_option("-m", action="store_true", default=False, help=hlp)
parser.add_option("-n", action="store_true", default=False,
help='Produce a ndiff format diff')
parser.add_option("-l", "--lines", type="int", default=3,
help='Set number of context lines (default 3)')
(options, args) = parser.parse_args()
if len(args) == 0:
parser.print_help()
sys.exit(1)
if len(args) != 2:
parser.error("need to specify both a fromfile and tofile")
n = options.lines
fromfile, tofile = args # as specified in the usage string
# we're passing these as arguments to the diff function
fromdate = time.ctime(os.stat(fromfile).st_mtime)
todate = time.ctime(os.stat(tofile).st_mtime)
with open(fromfile, 'U') as f:
fromlines = f.readlines()
with open(tofile, 'U') as f:
tolines = f.readlines()
if options.u:
diff = difflib.unified_diff(fromlines, tolines, fromfile, tofile,
fromdate, todate, n=n)
elif options.n:
diff = difflib.ndiff(fromlines, tolines)
elif options.m:
diff = difflib.HtmlDiff().make_file(fromlines, tolines, fromfile,
tofile, context=options.c,
numlines=n)
else:
diff = difflib.context_diff(fromlines, tolines, fromfile, tofile,
fromdate, todate, n=n)
# we're using writelines because diff is a generator
sys.stdout.writelines(diff)
if __name__ == '__main__':
main()

62
Doc/library/dircache.rst Normal file
View File

@@ -0,0 +1,62 @@
:mod:`dircache` --- Cached directory listings
=============================================
.. module:: dircache
:synopsis: Return directory listing, with cache mechanism.
:deprecated:
.. deprecated:: 2.6
The :mod:`dircache` module has been removed in Python 3.
.. 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']

907
Doc/library/dis.rst Normal file
View File

@@ -0,0 +1,907 @@
:mod:`dis` --- Disassembler for Python bytecode
===============================================
.. module:: dis
:synopsis: Disassembler for Python bytecode.
**Source code:** :source:`Lib/dis.py`
--------------
The :mod:`dis` module supports the analysis of CPython :term:`bytecode` by
disassembling it. The CPython bytecode which this module takes as an input is
defined in the file :file:`Include/opcode.h` and used by the compiler and the
interpreter.
.. impl-detail::
Bytecode is an implementation detail of the CPython interpreter! No
guarantees are made that bytecode will not be added, removed, or changed
between versions of Python. Use of this module should not be considered to
work across Python VMs or Python releases.
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 bytecode 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 :func:`disassemble`. It is more convenient to type, and kept
for compatibility with earlier Python releases.
.. function:: findlinestarts(code)
This generator function uses the ``co_firstlineno`` and ``co_lnotab``
attributes of the code object *code* to find the offsets which are starts of
lines in the source code. They are generated as ``(offset, lineno)`` pairs.
.. function:: findlabels(code)
Detect all offsets in the code object *code* which are jump targets, and
return a list of these offsets.
.. data:: opname
Sequence of operation names, indexable using the bytecode.
.. data:: opmap
Dictionary mapping operation names to bytecodes.
.. data:: cmp_op
Sequence of all compare operation names.
.. data:: hasconst
Sequence of bytecodes that access a constant.
.. data:: hasfree
Sequence of bytecodes that access a free variable.
.. data:: hasname
Sequence of bytecodes that access an attribute by name.
.. data:: hasjrel
Sequence of bytecodes that have a relative jump target.
.. data:: hasjabs
Sequence of bytecodes that have an absolute jump target.
.. data:: haslocal
Sequence of bytecodes that access a local variable.
.. data:: hascompare
Sequence of bytecodes of Boolean operations.
.. _bytecodes:
Python Bytecode Instructions
----------------------------
The Python compiler currently generates the following bytecode 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_CONVERT ()
Implements ``TOS = `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_DIVIDE ()
Implements ``TOS = TOS1 / TOS`` when ``from __future__ import division`` is
not in effect.
.. 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_DIVIDE ()
Implements in-place ``TOS = TOS1 / TOS`` when ``from __future__ import
division`` is not in effect.
.. 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 :opcode:`POP_TOP`.
.. opcode:: PRINT_ITEM ()
Prints TOS to the file-like object bound to ``sys.stdout``. There is one
such instruction for each item in the :keyword:`print` statement.
.. opcode:: PRINT_ITEM_TO ()
Like ``PRINT_ITEM``, but prints the item second from TOS to the file-like
object at TOS. This is used by the extended print statement.
.. opcode:: PRINT_NEWLINE ()
Prints a new line on ``sys.stdout``. This is generated as the last operation
of a :keyword:`print` statement, unless the statement ends with a comma.
.. opcode:: PRINT_NEWLINE_TO ()
Like ``PRINT_NEWLINE``, but prints the new line on the file-like object on
the TOS. This is used by the extended print statement.
.. 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 :opcode:`FOR_ITER` instruction).
.. opcode:: LIST_APPEND (i)
Calls ``list.append(TOS[-i], TOS)``. Used to implement list comprehensions.
While the appended value is popped off, the list object remains on the stack
so that it is available for further iterations of the loop.
.. 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 :term:`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:: EXEC_STMT ()
Implements ``exec TOS2,TOS1,TOS``. The compiler fills missing optional
parameters with ``None``.
.. 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.
.. opcode:: SETUP_WITH (delta)
This opcode performs several operations before a with block starts. First,
it loads :meth:`~object.__exit__` from the context manager and pushes it onto
the stack for later use by :opcode:`WITH_CLEANUP`. Then,
:meth:`~object.__enter__` is called, and a finally block pointing to *delta*
is pushed. Finally, the result of calling the enter method is pushed onto
the stack. The next opcode will either ignore it (:opcode:`POP_TOP`), or
store it in (a) variable(s) (:opcode:`STORE_FAST`, :opcode:`STORE_NAME`, or
:opcode:`UNPACK_SEQUENCE`).
.. opcode:: WITH_CLEANUP ()
Cleans up the stack when a :keyword:`with` statement block exits. On top of
the stack are 1--3 values indicating how/why the finally clause was entered:
* TOP = ``None``
* (TOP, SECOND) = (``WHY_{RETURN,CONTINUE}``), retval
* TOP = ``WHY_*``; no retval below it
* (TOP, SECOND, THIRD) = exc_info()
Under them is EXIT, the context manager's :meth:`__exit__` bound method.
In the last case, ``EXIT(TOP, SECOND, THIRD)`` is called, otherwise
``EXIT(None, None, None)``.
EXIT is removed from the stack, leaving the values above it in the same
order. In addition, if the stack represents an exception, *and* the function
call returns a 'true' value, this information is "zapped", to prevent
``END_FINALLY`` from re-raising the exception. (But non-local gotos should
still be resumed.)
.. XXX explain the WHY stuff!
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_FAST``
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.
.. 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.
.. 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.
.. versionadded:: 2.7
.. opcode:: BUILD_MAP (count)
Pushes a new dictionary object onto the stack. The dictionary is pre-sized
to hold *count* entries.
.. 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]``. TOS and TOS1 are popped and provide
the *fromlist* and *level* arguments of :func:`__import__`. 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 bytecode counter by *delta*.
.. opcode:: POP_JUMP_IF_TRUE (target)
If TOS is true, sets the bytecode counter to *target*. TOS is popped.
.. opcode:: POP_JUMP_IF_FALSE (target)
If TOS is false, sets the bytecode counter to *target*. TOS is popped.
.. opcode:: JUMP_IF_TRUE_OR_POP (target)
If TOS is true, sets the bytecode counter to *target* and leaves TOS on the
stack. Otherwise (TOS is false), TOS is popped.
.. opcode:: JUMP_IF_FALSE_OR_POP (target)
If TOS is false, sets the bytecode counter to *target* and leaves TOS on the
stack. Otherwise (TOS is true), TOS is popped.
.. opcode:: JUMP_ABSOLUTE (target)
Set bytecode counter to *target*.
.. opcode:: FOR_ITER (delta)
``TOS`` is an :term:`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 bytecode
counter is incremented by *delta*.
.. opcode:: LOAD_GLOBAL (namei)
Loads the global named ``co_names[namei]`` onto the stack.
.. 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:: STORE_MAP ()
Store a key and value pair in a dictionary. Pops the key and value while
leaving the dictionary on the stack.
.. 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 arguments 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 callable object. The low byte of *argc* indicates the number of
positional arguments, the high byte the number of keyword arguments.
The stack contains keyword arguments on top (if any), then the positional
arguments below that (if any), then the callable object to call below that.
Each keyword argument is represented with two values on the stack:
the argument's name, and its value, with the argument's value above the
name on the stack.
The positional arguments are pushed in the order that they are passed in
to the callable object, with the right-most positional argument on top.
``CALL_FUNCTION`` pops all arguments and the callable object off the stack,
calls the callable object with those arguments, and pushes the return value
returned by the callable object.
.. 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 *func_closure* slot, and pushes it on
the stack. TOS is the code associated with the function, TOS1 the tuple
containing cells for the closure's free variables. The function also has
*argc* default parameters, which are found below 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 :func:`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 callable object, similarly to :opcode:`CALL_FUNCTION`.
*argc* represents the number of keyword and positional
arguments, identically to :opcode:`CALL_FUNCTION`.
The top of the stack contains an iterable object containing
additional positional arguments.
Below that are keyword arguments (if any), positional arguments (if any)
and a callable object, identically to :opcode:`CALL_FUNCTION`.
Before the callable object is called, the iterable object
is "unpacked" and its contents are appended to the positional
arguments passed in.
The iterable object is ignored when computing
the value of ``argc``.
.. opcode:: CALL_FUNCTION_KW (argc)
Calls a callable object, similarly to :opcode:`CALL_FUNCTION`.
*argc* represents the number of keyword and positional
arguments, identically to :opcode:`CALL_FUNCTION`.
The top of the stack contains a mapping object containing additional keyword
arguments.
Below that are keyword arguments (if any), positional arguments (if any)
and a callable object, identically to :opcode:`CALL_FUNCTION`.
Before the callable is called, the mapping object at the top of the stack is
"unpacked" and its contents are appended to the keyword arguments passed in.
The mapping object at the top of the stack is ignored when computing
the value of ``argc``.
.. opcode:: CALL_FUNCTION_VAR_KW (argc)
Calls a callable object, similarly to :opcode:`CALL_FUNCTION_VAR` and
:opcode:`CALL_FUNCTION_KW`.
*argc* represents the number of keyword and positional
arguments, identically to :opcode:`CALL_FUNCTION`.
The top of the stack contains a mapping object, as per
:opcode:`CALL_FUNCTION_KW`.
Below that is an iterable object, as per
:opcode:`CALL_FUNCTION_VAR`.
Below that are keyword arguments (if any), positional arguments (if any)
and a callable object, identically to :opcode:`CALL_FUNCTION`.
Before the callable is called, the mapping object and iterable object
are each "unpacked" and their contents passed in as keyword and
positional arguments respectively,
identically to :opcode:`CALL_FUNCTION_VAR` and :opcode:`CALL_FUNCTION_KW`.
The mapping object and iterable object are both ignored when computing
the value of ``argc``.
.. 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``.

13
Doc/library/distribution.rst Normal file
View File

@@ -0,0 +1,13 @@
***********************************
Software Packaging and Distribution
***********************************
These libraries help you with publishing and installing Python software.
While these modules are designed to work in conjunction with the
`Python Package Index <https://pypi.org>`__, they can also be used
with a local index server, or without any index server at all.
.. toctree::
distutils.rst
ensurepip.rst

42
Doc/library/distutils.rst Normal file
View File

@@ -0,0 +1,42 @@
: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.
Most Python users will *not* want to use this module directly, but instead
use the cross-version tools maintained by the Python Packaging Authority. In
particular,
`setuptools <https://setuptools.readthedocs.io/en/latest/>`__ is an
enhanced alternative to :mod:`distutils` that provides:
* support for declaring project dependencies
* additional mechanisms for configuring which files to include in source
releases (including plugins for integration with version control systems)
* the ability to declare project "entry points", which can be used as the
basis for application plugin systems
* the ability to automatically generate Windows command line executables at
installation time rather than needing to prebuild them
* consistent behaviour across all supported Python versions
The recommended `pip <https://pip.pypa.io/>`__ installer runs all
``setup.py`` scripts with ``setuptools``, even if the script itself only
imports ``distutils``. Refer to the
`Python Packaging User Guide <https://packaging.python.org>`_ for more
information.
For the benefits of packaging tool authors and users seeking a deeper
understanding of the details of the current packaging and distribution
system, the legacy :mod:`distutils` based user documentation and API
reference remain available:
* :ref:`install-index`
* :ref:`distutils-index`

114
Doc/library/dl.rst Normal file
View File

@@ -0,0 +1,114 @@
:mod:`dl` --- Call C functions in shared objects
================================================
.. module:: dl
:platform: Unix
:synopsis: Call C functions in shared objects.
:deprecated:
.. deprecated:: 2.6
The :mod:`dl` module has been removed in Python 3. Use the :mod:`ctypes`
module instead.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
The :mod:`dl` module defines an interface to the :c:func:`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 :c:type:`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 :c:type:`long`, which is a
Python integer.

1932
Doc/library/doctest.rst Normal file
View File

File diff suppressed because it is too large Load Diff

101
Doc/library/docxmlrpcserver.rst Normal file
View File

@@ -0,0 +1,101 @@
: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>
.. note::
The :mod:`DocXMLRPCServer` module has been merged into :mod:`xmlrpc.server`
in Python 3. The :term:`2to3` tool will automatically adapt imports when
converting your sources to Python 3.
.. 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.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.DocXMLRPCServer` constructor parameter is
honored.
.. _doc-xmlrpc-servers:
DocXMLRPCServer Objects
-----------------------
The :class:`~DocXMLRPCServer.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.

92
Doc/library/dumbdbm.rst Normal file
View File

@@ -0,0 +1,92 @@
:mod:`dumbdbm` --- Portable DBM implementation
==============================================
.. module:: dumbdbm
:synopsis: Portable implementation of the simple DBM interface.
.. note::
The :mod:`dumbdbm` module has been renamed to :mod:`dbm.dumb` in Python 3.
The :term:`2to3` tool will automatically adapt imports when converting your
sources to Python 3.
.. 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.
In addition to the dictionary-like methods, ``dumbdm`` objects
provide the following method:
.. function:: close()
Close the ``dumbdm`` database.
.. 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.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.

31
Doc/library/dummy_thread.rst Normal file
View File

@@ -0,0 +1,31 @@
:mod:`dummy_thread` --- Drop-in replacement for the :mod:`thread` module
========================================================================
.. module:: dummy_thread
:synopsis: Drop-in replacement for the thread module.
.. note::
The :mod:`dummy_thread` module has been renamed to :mod:`_dummy_thread` in
Python 3. The :term:`2to3` tool will automatically adapt imports when
converting your sources to Python 3; however, you should consider using the
high-lever :mod:`dummy_threading` module instead.
**Source code:** :source:`Lib/dummy_thread.py`
--------------
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.

25
Doc/library/dummy_threading.rst Normal file
View File

@@ -0,0 +1,25 @@
:mod:`dummy_threading` --- Drop-in replacement for the :mod:`threading` module
==============================================================================
.. module:: dummy_threading
:synopsis: Drop-in replacement for the threading module.
**Source code:** :source:`Lib/dummy_threading.py`
--------------
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.

215
Doc/library/easydialogs.rst Normal file
View File

@@ -0,0 +1,215 @@
:mod:`EasyDialogs` --- Basic Macintosh dialogs
==============================================
.. module:: EasyDialogs
:platform: Mac
:synopsis: Basic Macintosh dialogs.
:deprecated:
The :mod:`EasyDialogs` module contains some simple dialogs for the Macintosh.
The dialogs get launched in a separate application which appears in the dock and
must be clicked on for the dialogs be displayed. All routines take an optional
resource ID parameter *id* with which one can override the :const:`DLOG`
resource used for the dialog, provided that the dialog items correspond (both
type and item number) to those in the default :const:`DLOG` resource. See source
code for details.
.. note::
This module has been removed in Python 3.x.
The :mod:`EasyDialogs` module defines the following functions:
.. function:: Message(str[, id[, ok]])
Displays a modal dialog with the message text *str*, which should be at most 255
characters long. The button text defaults to "OK", but is set to the string
argument *ok* if the latter is supplied. Control is returned when the user
clicks the "OK" button.
.. function:: AskString(prompt[, default[, id[, ok[, cancel]]]])
Asks the user to input a string value via a modal dialog. *prompt* is the prompt
message, and the optional *default* supplies the initial value for the string
(otherwise ``""`` is used). The text of the "OK" and "Cancel" buttons can be
changed with the *ok* and *cancel* arguments. All strings can be at most 255
bytes long. :func:`AskString` returns the string entered or :const:`None` in
case the user cancelled.
.. function:: AskPassword(prompt[, default[, id[, ok[, cancel]]]])
Asks the user to input a string value via a modal dialog. Like
:func:`AskString`, but with the text shown as bullets. The arguments have the
same meaning as for :func:`AskString`.
.. function:: AskYesNoCancel(question[, default[, yes[, no[, cancel[, id]]]]])
Presents a dialog with prompt *question* and three buttons labelled "Yes", "No",
and "Cancel". Returns ``1`` for "Yes", ``0`` for "No" and ``-1`` for "Cancel".
The value of *default* (or ``0`` if *default* is not supplied) is returned when
the :kbd:`RETURN` key is pressed. The text of the buttons can be changed with
the *yes*, *no*, and *cancel* arguments; to prevent a button from appearing,
supply ``""`` for the corresponding argument.
.. function:: ProgressBar([title[, maxval[, label[, id]]]])
Displays a modeless progress-bar dialog. This is the constructor for the
:class:`ProgressBar` class described below. *title* is the text string displayed
(default "Working..."), *maxval* is the value at which progress is complete
(default ``0``, indicating that an indeterminate amount of work remains to be
done), and *label* is the text that is displayed above the progress bar itself.
.. function:: GetArgv([optionlist[ commandlist[, addoldfile[, addnewfile[, addfolder[, id]]]]]])
Displays a dialog which aids the user in constructing a command-line argument
list. Returns the list in ``sys.argv`` format, suitable for passing as an
argument to :func:`getopt.getopt`. *addoldfile*, *addnewfile*, and *addfolder*
are boolean arguments. When nonzero, they enable the user to insert into the
command line paths to an existing file, a (possibly) not-yet-existent file, and
a folder, respectively. (Note: Option arguments must appear in the command line
before file and folder arguments in order to be recognized by
:func:`getopt.getopt`.) Arguments containing spaces can be specified by
enclosing them within single or double quotes. A :exc:`SystemExit` exception is
raised if the user presses the "Cancel" button.
*optionlist* is a list that determines a popup menu from which the allowed
options are selected. Its items can take one of two forms: *optstr* or
``(optstr, descr)``. When present, *descr* is a short descriptive string that
is displayed in the dialog while this option is selected in the popup menu. The
correspondence between *optstr*\s and command-line arguments is:
+----------------------+------------------------------------------+
| *optstr* format | Command-line format |
+======================+==========================================+
| ``x`` | :option:`!-x` (short option) |
+----------------------+------------------------------------------+
| ``x:`` or ``x=`` | :option:`!-x` (short option with value) |
+----------------------+------------------------------------------+
| ``xyz`` | :option:`!--xyz` (long option) |
+----------------------+------------------------------------------+
| ``xyz:`` or ``xyz=`` | :option:`!--xyz` (long option with value)|
+----------------------+------------------------------------------+
*commandlist* is a list of items of the form *cmdstr* or ``(cmdstr, descr)``,
where *descr* is as above. The *cmdstr*\ s will appear in a popup menu. When
chosen, the text of *cmdstr* will be appended to the command line as is, except
that a trailing ``':'`` or ``'='`` (if present) will be trimmed off.
.. versionadded:: 2.0
.. function:: AskFileForOpen( [message] [, typeList] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, eventProc] [, previewProc] [, filterProc] [, wanted] )
Post a dialog asking the user for a file to open, and return the file selected
or :const:`None` if the user cancelled. *message* is a text message to display,
*typeList* is a list of 4-char filetypes allowable, *defaultLocation* is the
pathname, :class:`FSSpec` or :class:`FSRef` of the folder to show initially,
*location* is the ``(x, y)`` position on the screen where the dialog is shown,
*actionButtonLabel* is a string to show instead of "Open" in the OK button,
*cancelButtonLabel* is a string to show instead of "Cancel" in the cancel
button, *wanted* is the type of value wanted as a return: :class:`str`,
:class:`unicode`, :class:`FSSpec`, :class:`FSRef` and subtypes thereof are
acceptable.
.. index:: single: Navigation Services
For a description of the other arguments please see the Apple Navigation
Services documentation and the :mod:`EasyDialogs` source code.
.. function:: AskFileForSave( [message] [, savedFileName] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, fileType] [, fileCreator] [, eventProc] [, wanted] )
Post a dialog asking the user for a file to save to, and return the file
selected or :const:`None` if the user cancelled. *savedFileName* is the default
for the file name to save to (the return value). See :func:`AskFileForOpen` for
a description of the other arguments.
.. function:: AskFolder( [message] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, eventProc] [, filterProc] [, wanted] )
Post a dialog asking the user to select a folder, and return the folder selected
or :const:`None` if the user cancelled. See :func:`AskFileForOpen` for a
description of the arguments.
.. seealso::
`Navigation Services Reference <http://developer.apple.com/legacy/mac/library/#documentation/Carbon/Conceptual/NavServicesIntro/ns_intro_carb/ns_into_carb.html>`_
Programmer's reference documentation for the Navigation Services, a part of the
Carbon framework.
.. _progressbar-objects:
ProgressBar Objects
-------------------
:class:`ProgressBar` objects provide support for modeless progress-bar dialogs.
Both determinate (thermometer style) and indeterminate (barber-pole style)
progress bars are supported. The bar will be determinate if its maximum value
is greater than zero; otherwise it will be indeterminate.
.. versionchanged:: 2.2
Support for indeterminate-style progress bars was added.
The dialog is displayed immediately after creation. If the dialog's "Cancel"
button is pressed, or if :kbd:`Cmd-.` or :kbd:`ESC` is typed, the dialog window
is hidden and :exc:`KeyboardInterrupt` is raised (but note that this response
does not occur until the progress bar is next updated, typically via a call to
:meth:`inc` or :meth:`set`). Otherwise, the bar remains visible until the
:class:`ProgressBar` object is discarded.
:class:`ProgressBar` objects possess the following attributes and methods:
.. attribute:: ProgressBar.curval
The current value (of type integer or long integer) of the progress bar. The
normal access methods coerce :attr:`curval` between ``0`` and :attr:`maxval`.
This attribute should not be altered directly.
.. attribute:: ProgressBar.maxval
The maximum value (of type integer or long integer) of the progress bar; the
progress bar (thermometer style) is full when :attr:`curval` equals
:attr:`maxval`. If :attr:`maxval` is ``0``, the bar will be indeterminate
(barber-pole). This attribute should not be altered directly.
.. method:: ProgressBar.title([newstr])
Sets the text in the title bar of the progress dialog to *newstr*.
.. method:: ProgressBar.label([newstr])
Sets the text in the progress box of the progress dialog to *newstr*.
.. method:: ProgressBar.set(value[, max])
Sets the progress bar's :attr:`curval` to *value*, and also :attr:`maxval` to
*max* if the latter is provided. *value* is first coerced between 0 and
:attr:`maxval`. The thermometer bar is updated to reflect the changes,
including a change from indeterminate to determinate or vice versa.
.. method:: ProgressBar.inc([n])
Increments the progress bar's :attr:`curval` by *n*, or by ``1`` if *n* is not
provided. (Note that *n* may be negative, in which case the effect is a
decrement.) The progress bar is updated to reflect the change. If the bar is
indeterminate, this causes one "spin" of the barber pole. The resulting
:attr:`curval` is coerced between 0 and :attr:`maxval` if incrementing causes it
to fall outside this range.

46
Doc/library/email-examples.rst Normal file
View File

@@ -0,0 +1,46 @@
.. _email-examples:
:mod:`email`: 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:
.. literalinclude:: ../includes/email-simple.py
And parsing RFC822 headers can easily be done by the parse(filename) or
parsestr(message_as_string) methods of the Parser() class:
.. literalinclude:: ../includes/email-headers.py
Here's an example of how to send a MIME message containing a bunch of family
pictures that may be residing in a directory:
.. literalinclude:: ../includes/email-mime.py
Here's an example of how to send the entire contents of a directory as an email
message: [1]_
.. literalinclude:: ../includes/email-dir.py
Here's an example of how to unpack a MIME message like the one
above, into a directory of files:
.. literalinclude:: ../includes/email-unpack.py
Here's an example of how to create an HTML message with an alternative plain
text version: [2]_
.. literalinclude:: ../includes/email-alternative.py
.. rubric:: Footnotes
.. [1] Thanks to Matthew Dixon Cowles for the original inspiration and examples.
.. [2] Contributed by Martin Matejek.

253
Doc/library/email.charset.rst Normal file
View File

@@ -0,0 +1,253 @@
:mod:`email.charset`: Representing character sets
-------------------------------------------------
.. 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:
.. attribute:: 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``.
.. attribute:: 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``.
.. attribute:: 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*.
.. attribute:: 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``.
.. attribute:: 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``.
.. attribute:: 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:: 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:: convert(s)
Convert the string *s* from the *input_codec* to the *output_codec*.
.. method:: 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:: 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:: 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:: encoded_header_len()
Return the length of the encoded header string, properly calculating for
quoted-printable or base64 encoding.
.. method:: 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:`~email.header.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:: 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:: __str__()
Returns *input_charset* as a string coerced to lower
case. :meth:`__repr__` is an alias for :meth:`__str__`.
.. method:: __eq__(other)
This method allows you to compare two :class:`Charset` instances for
equality.
.. method:: __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:`~unicode.encode` method of a Unicode string.

61
Doc/library/email.encoders.rst Normal file
View File

@@ -0,0 +1,61 @@
:mod:`email.encoders`: Encoders
-------------------------------
.. module:: email.encoders
:synopsis: Encoders for email message payloads.
When creating :class:`~email.message.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:`~email.mime.audio.MIMEAudio` and :class:`~email.mime.image.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.
Note that these functions are not meaningful for a multipart message. They
must be applied to individual subparts instead, and will raise a
:exc:`TypeError` if passed a message whose type is multipart.
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.

95
Doc/library/email.errors.rst Normal file
View File

@@ -0,0 +1,95 @@
:mod:`email.errors`: Exception and Defect classes
-------------------------------------------------
.. 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 raised by the :class:`~email.parser.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 <email.parser.Parser.parse>` or
:meth:`Parser.parsestr <email.parser.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 <email.parser.Parser.parse>` or
:meth:`Parser.parsestr <email.parser.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:`~email.message.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:`~email.message.Message.attach`
method is called on an instance of a class derived from
:class:`~email.mime.nonmultipart.MIMENonMultipart` (e.g.
:class:`~email.mime.image.MIMEImage`).
Here's the list of the defects that the :class:`~email.parser.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:`~email.message.Message.is_multipart` method may
return false even though its content type claims to be :mimetype:`multipart`.

135
Doc/library/email.generator.rst Normal file
View File

@@ -0,0 +1,135 @@
:mod:`email.generator`: Generating MIME documents
-------------------------------------------------
.. 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:`~email.parser.Parser` class, and back to flat text,
is idempotent (the input is identical to the output) [#]_. On the other hand,
using the Generator on a :class:`~email.message.Message` constructed by program
may result in changes to the :class:`~email.message.Message` object as defaults
are filled in.
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
<https://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
:class:`~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:: 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:: clone(fp)
Return an independent clone of this :class:`Generator` instance with the
exact same options.
.. versionadded:: 2.2.2
.. method:: 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.
.. rubric:: Footnotes
.. [#] This statement assumes that you use the appropriate setting for the
``unixfrom`` argument, and that you set maxheaderlen=0 (which will
preserve whatever the input line lengths were). It is also not strictly
true, since in many cases runs of whitespace in headers are collapsed
into single blanks. The latter is a bug that will eventually be fixed.

175
Doc/library/email.header.rst Normal file
View File

@@ -0,0 +1,175 @@
:mod:`email.header`: Internationalized headers
----------------------------------------------
.. 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:`~email.message.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:`~email.message.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 explicitly 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. *continuation_ws* defaults to a single
space character (" ").
Optional *errors* is passed straight through to the :meth:`append` method.
.. method:: append(s[, charset[, errors]])
Append the string *s* to the MIME header.
Optional *charset*, if given, should be a :class:`~email.charset.Charset`
instance (see :mod:`email.charset`) or the name of a character set, which
will be converted to a :class:`~email.charset.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
:meth:`unicode.encode` call, and defaults to "strict".
.. method:: 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:: __str__()
A synonym for :meth:`Header.encode`. Useful for ``str(aHeader)``.
.. method:: __unicode__()
A helper for the built-in :func:`unicode` function. Returns the header as
a Unicode string.
.. method:: __eq__(other)
This method allows you to compare two :class:`Header` instances for
equality.
.. method:: __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.

68
Doc/library/email.iterators.rst Normal file
View File

@@ -0,0 +1,68 @@
:mod:`email.iterators`: Iterators
---------------------------------
.. module:: email.iterators
:synopsis: Iterate over a message object tree.
Iterating over a message object tree is fairly easy with the
:meth:`Message.walk <email.message.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:`~io.TextIOBase.readline`, skipping over all the
intervening headers.
Optional *decode* is passed through to :meth:`Message.get_payload
<email.message.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.

603
Doc/library/email.message.rst Normal file
View File

@@ -0,0 +1,603 @@
:mod:`email.message`: Representing an email message
---------------------------------------------------
.. 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:: as_string([unixfrom])
Return the entire message flattened as a string. When optional *unixfrom*
is ``True``, the envelope header is included in the returned string.
*unixfrom* defaults to ``False``. Flattening the message may trigger
changes to the :class:`Message` if defaults need to be filled in to
complete the transformation to a string (for example, MIME boundaries may
be generated or modified).
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:`~email.generator.Generator` instance and use its
:meth:`~email.generator.Generator.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:: __str__()
Equivalent to ``as_string(unixfrom=True)``.
.. method:: 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:: set_unixfrom(unixfrom)
Set the message's envelope header to *unixfrom*, which should be a string.
.. method:: get_unixfrom()
Return the message's envelope header. Defaults to ``None`` if the
envelope header was never set.
.. method:: 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:: get_payload([i[, decode]])
Return 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:: 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:: set_charset(charset)
Set the character set of the payload to *charset*, which can either be a
:class:`~email.charset.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:`~email.charset.Charset` instance. If *charset*
is ``None``, the ``charset`` parameter will be removed from the
:mailheader:`Content-Type` header (the message will not be otherwise
modified). Anything else will generate a :exc:`TypeError`.
If there is no existing :mailheader:`MIME-Version` header one will be
added. If there is no existing :mailheader:`Content-Type` header, one
will be added with a value of :mimetype:`text/plain`. Whether the
:mailheader:`Content-Type` header already exists or not, its ``charset``
parameter will be set to *charset.output_charset*. If
*charset.input_charset* and *charset.output_charset* differ, the payload
will be re-encoded to the *output_charset*. If there is no existing
:mailheader:`Content-Transfer-Encoding` header, then the payload will be
transfer-encoded, if needed, using the specified
:class:`~email.charset.Charset`, and a header with the appropriate value
will be added. If a :mailheader:`Content-Transfer-Encoding` header
already exists, the payload is assumed to already be correctly encoded
using that :mailheader:`Content-Transfer-Encoding` and is not modified.
The message will be assumed to be of type :mimetype:`text/\*`, with the
payload either in unicode or encoded with *charset.input_charset*.
It will be encoded or converted to *charset.output_charset*
and transfer 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:: get_charset()
Return the :class:`~email.charset.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:: __len__()
Return the total number of headers, including duplicates.
.. method:: __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:: __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:: __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:: __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:: has_key(name)
Return true if the message contains a header field named *name*, otherwise
return false.
.. method:: keys()
Return a list of all the message's header field names.
.. method:: values()
Return a list of all the message's field values.
.. method:: items()
Return a list of 2-tuples containing all the message's field headers and
values.
.. method:: 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:: 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:: 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. If the value contains non-ASCII characters,
it must be specified as a three tuple in the format
``(CHARSET, LANGUAGE, VALUE)``, where ``CHARSET`` is a string naming the
charset to be used to encode the value, ``LANGUAGE`` can usually be set
to ``None`` or the empty string (see :RFC:`2231` for other possibilities),
and ``VALUE`` is the string value containing non-ASCII code points.
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"
An example with non-ASCII characters::
msg.add_header('Content-Disposition', 'attachment',
filename=('iso-8859-1', '', 'Fußballer.ppt'))
Which produces ::
Content-Disposition: attachment; filename*="iso-8859-1''Fu%DFballer.ppt"
.. method:: 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:: 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:: 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:: 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:: 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:: 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:: 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:: 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 when 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:: 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:: 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:: 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:: 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 on the :mailheader:`Content-Type` header. If
neither is found, or the header is missing, then *failobj* is returned.
The returned string will always be unquoted as per
:func:`email.utils.unquote`.
.. method:: 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 :func:`email.utils.unquote`.
.. method:: 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:`~email.errors.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:: 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:`~email.charset.Charset` instance for the default encoding of the message body.
.. versionadded:: 2.2.2
.. method:: 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:: 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.
.. attribute:: 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:`~email.parser.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:`~email.generator.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``.
.. attribute:: 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:`~email.generator.Generator` to print a newline at the end of the
file.
.. attribute:: 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

219
Doc/library/email.mime.rst Normal file
View File

@@ -0,0 +1,219 @@
:mod:`email.mime`: Creating email and MIME objects from scratch
---------------------------------------------------------------
.. module:: email.mime
:synopsis: Build MIME messages.
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:`~email.message.Message` objects by hand. In fact, you can also take an
existing structure and add new :class:`~email.message.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:`~email.message.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:
.. currentmodule:: email.mime.base
.. class:: MIMEBase(_maintype, _subtype, **_params)
Module: :mod:`email.mime.base`
This is the base class for all the MIME-specific subclasses of
:class:`~email.message.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
<email.message.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``).
.. currentmodule:: email.mime.nonmultipart
.. class:: MIMENonMultipart()
Module: :mod:`email.mime.nonmultipart`
A subclass of :class:`~email.mime.base.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:`~email.message.Message.attach` method, which only makes sense for
:mimetype:`multipart` messages. If :meth:`~email.message.Message.attach`
is called, a :exc:`~email.errors.MultipartConversionError` exception is raised.
.. versionadded:: 2.2.2
.. currentmodule:: email.mime.multipart
.. class:: MIMEMultipart([_subtype[, boundary[, _subparts[, _params]]]])
Module: :mod:`email.mime.multipart`
A subclass of :class:`~email.mime.base.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 (for example, when the
message is serialized).
*_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
<email.message.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
.. currentmodule:: email.mime.application
.. class:: MIMEApplication(_data[, _subtype[, _encoder[, **_params]]])
Module: :mod:`email.mime.application`
A subclass of :class:`~email.mime.nonmultipart.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:`~email.message.Message.get_payload` and
:meth:`~email.message.Message.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
.. currentmodule:: email.mime.audio
.. class:: MIMEAudio(_audiodata[, _subtype[, _encoder[, **_params]]])
Module: :mod:`email.mime.audio`
A subclass of :class:`~email.mime.nonmultipart.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:`~email.message.Message.get_payload` and
:meth:`~email.message.Message.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.
.. currentmodule:: email.mime.image
.. class:: MIMEImage(_imagedata[, _subtype[, _encoder[, **_params]]])
Module: :mod:`email.mime.image`
A subclass of :class:`~email.mime.nonmultipart.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:`~email.message.Message.get_payload` and
:meth:`~email.message.Message.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:`~email.mime.base.MIMEBase`
constructor.
.. currentmodule:: email.mime.message
.. class:: MIMEMessage(_msg[, _subtype])
Module: :mod:`email.mime.message`
A subclass of :class:`~email.mime.nonmultipart.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:`~email.message.Message` (or a subclass thereof), otherwise
a :exc:`TypeError` is raised.
Optional *_subtype* sets the subtype of the message; it defaults to
:mimetype:`rfc822`.
.. currentmodule:: email.mime.text
.. class:: MIMEText(_text[, _subtype[, _charset]])
Module: :mod:`email.mime.text`
A subclass of :class:`~email.mime.nonmultipart.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:`~email.mime.nonmultipart.MIMENonMultipart` constructor; it defaults
to ``us-ascii``. If *_text* is unicode, it is encoded using the
*output_charset* of *_charset*, otherwise it is used as-is.
.. versionchanged:: 2.4
The previously deprecated *_encoding* argument has been removed. Content
Transfer Encoding now happens implicitly based on the *_charset*
argument.
Unless the ``_charset`` parameter is explicitly set to ``None``, the
MIMEText object created will have both a :mailheader:`Content-Type` header
with a ``charset`` parameter, and a :mailheader:`Content-Transfer-Encoding`
header. This means that a subsequent ``set_payload`` call will not result
in an encoded payload, even if a charset is passed in the ``set_payload``
command. You can "reset" this behavior by deleting the
``Content-Transfer-Encoding`` header, after which a ``set_payload`` call
will automatically encode the new payload (and add a new
:mailheader:`Content-Transfer-Encoding` header).

230
Doc/library/email.parser.rst Normal file
View File

@@ -0,0 +1,230 @@
:mod:`email.parser`: Parsing email messages
-------------------------------------------
.. 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:`~email.message.Message` objects and
stringing them together via :meth:`~email.message.Message.attach` and
:meth:`~email.message.Message.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:`~email.message.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:`~email.message.Message.is_multipart` method, and
the subparts can be accessed via the :meth:`~email.message.Message.get_payload`
and :meth:`~email.message.Message.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:`~email.message.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:: 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:: 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:`~email.message.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:: 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:`~io.TextIOBase.readline` and the :meth:`~io.TextIOBase.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 an
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 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.
.. method:: 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.StringIO` instance first and
calling :meth:`parse`.
Optional *headersonly* is as with the :meth:`parse` method.
.. 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.
.. currentmodule:: email
.. 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:`~email.parser.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:`~email.parser.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:`~email.message.Message.is_multipart`. Their
:meth:`~email.message.Message.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:`~email.message.Message.is_multipart` and their
:meth:`~email.message.Message.get_payload` method will return the list of
:class:`~email.message.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:`~email.message.Message.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:`~email.message.Message.is_multipart` method may return ``False``.
If such messages were parsed with the :class:`~email.parser.FeedParser`,
they will have an instance of the
:class:`~email.errors.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:`~email.parser.Parser` was re-implemented in terms of the
:class:`~email.parser.FeedParser`, so the semantics and results are
identical between the two parsers.

346
Doc/library/email.rst Normal file
View File

@@ -0,0 +1,346 @@
: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>
.. Copyright (C) 2001-2007 Python Software Foundation
.. 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.
Contents of the :mod:`email` package documentation:
.. toctree::
email.message.rst
email.parser.rst
email.generator.rst
email.mime.rst
email.header.rst
email.charset.rst
email.encoders.rst
email.errors.rst
email.utils.rst
email.iterators.rst
email-examples.rst
.. seealso::
Module :mod:`smtplib`
SMTP protocol client
Module :mod:`nntplib`
NNTP protocol client
.. _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:`~email.mime.application.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 <email.message.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:`~email.parser.FeedParser` class was introduced, and the
:class:`~email.parser.Parser` class was implemented in terms of the
:class:`~email.parser.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:`~email.mime.text.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:`~email.parser.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:`~email.message.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:`~email.message.Message` instances, be aware that in
:mod:`email` version 2, :class:`~email.message.Message` instances now have
private variables *_charset* and *_default_type*.
* Several methods in the :class:`~email.message.Message` class have been
deprecated, or their signatures changed. Also, many new methods have been
added. See the documentation for the :class:`~email.message.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:`~email.message.Message.is_multipart` returned false,
:meth:`~email.message.Message.get_payload` was not a list object, but a
single :class:`~email.message.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:`~email.message.Message.is_multipart`, and
:meth:`~email.message.Message.get_payload` returns a list containing a single
:class:`~email.message.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:`~email.message.Message.get_payload`, you should be fine. You just need
to make sure your code doesn't do a :meth:`~email.message.Message.set_payload`
with a :class:`~email.message.Message` instance on a container with a content
type of :mimetype:`message/rfc822`.
* The :class:`~email.parser.Parser` constructor's *strict* argument was added,
and its :meth:`~email.parser.Parser.parse` and
:meth:`~email.parser.Parser.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
<email.generator.Generator.flatten>` instead. The
:class:`~email.generator.Generator` class has also grown the
:meth:`~email.generator.Generator.clone` method.
* The :class:`~email.generator.DecodedGenerator` class in the
:mod:`email.generator` module was added.
* The intermediate base classes
:class:`~email.mime.nonmultipart.MIMENonMultipart` and
:class:`~email.mime.multipart.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:`~email.mime.text.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.sourceforge.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:`~email.message.Message` class has the following differences:
* The method :meth:`asString` was renamed to
:meth:`~email.message.Message.as_string`.
* The method :meth:`ismultipart` was renamed to
:meth:`~email.message.Message.is_multipart`.
* The :meth:`~email.message.Message.get_payload` method has grown a *decode*
optional argument.
* The method :meth:`getall` was renamed to
:meth:`~email.message.Message.get_all`.
* The method :meth:`addheader` was renamed to
:meth:`~email.message.Message.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:`~email.message.Message.get_params`. Also, whereas :meth:`getparams`
returned a list of strings, :meth:`~email.message.Message.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:`~email.message.Message.get_param`.
* The method :meth:`getcharsets` was renamed to
:meth:`~email.message.Message.get_charsets`.
* The method :meth:`getfilename` was renamed to
:meth:`~email.message.Message.get_filename`.
* The method :meth:`getboundary` was renamed to
:meth:`~email.message.Message.get_boundary`.
* The method :meth:`setboundary` was renamed to
:meth:`~email.message.Message.set_boundary`.
* The method :meth:`getdecodedpayload` was removed. To get similar
functionality, pass the value 1 to the *decode* flag of the
:meth:`~email.message.Message.get_payload` method.
* The method :meth:`getpayloadastext` was removed. Similar functionality is
supported by the :class:`~email.generator.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:`~email.iterators.typed_subpart_iterator` in the :mod:`email.iterators`
module.
The :class:`~email.parser.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:`~email.message.Message` instance containing separate
:class:`~email.message.Message` subparts for each header block in the delivery
status notification [#]_.
The :class:`~email.generator.Generator` class has no differences in its public
interface. There is a new class in the :mod:`email.generator` module though,
called :class:`~email.generator.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:`~email.mime.base.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:`~email.mime.message.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:`~email.iterators.body_line_iterator` function
in the :mod:`email.iterators` module.
.. rubric:: Footnotes
.. [#] Delivery Status Notifications (DSN) are defined in :rfc:`1894`.

164
Doc/library/email.utils.rst Normal file
View File

@@ -0,0 +1,164 @@
:mod:`email.utils`: Miscellaneous utilities
-------------------------------------------
.. 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 <email.message.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 (seconds since the Epoch). If the timezone item in the
tuple is ``None``, assume local time.
.. 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``. The default 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 <email.message.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 <email.header.Header.decode_header>` method
instead.
.. versionchanged:: 2.4
The :func:`encode` function has been removed; use the :meth:`Header.encode
<email.header.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`.

133
Doc/library/ensurepip.rst Normal file
View File

@@ -0,0 +1,133 @@
:mod:`ensurepip` --- Bootstrapping the ``pip`` installer
========================================================
.. module:: ensurepip
:synopsis: Bootstrapping the ``pip`` installer into an existing Python
installation or virtual environment.
.. versionadded:: 2.7.9
The :mod:`ensurepip` package provides support for bootstrapping the ``pip``
installer into an existing Python installation or virtual environment. This
bootstrapping approach reflects the fact that ``pip`` is an independent
project with its own release cycle, and the latest available stable version
is bundled with maintenance and feature releases of the CPython reference
interpreter.
In most cases, end users of Python shouldn't need to invoke this module
directly (as ``pip`` should be bootstrapped by default), but it may be
needed if installing ``pip`` was skipped when installing Python (or
when creating a virtual environment) or after explicitly uninstalling ``pip``.
.. note::
This module *does not* access the internet. All of the components
needed to bootstrap ``pip`` are included as internal parts of the
package.
.. seealso::
:ref:`installing-index`
The end user guide for installing Python packages
:pep:`453`: Explicit bootstrapping of pip in Python installations
The original rationale and specification for this module.
:pep:`477`: Backport ensurepip (PEP 453) to Python 2.7
The rationale and specification for backporting PEP 453 to Python 2.7.
Command line interface
----------------------
The command line interface is invoked using the interpreter's ``-m`` switch.
The simplest possible invocation is::
python -m ensurepip
This invocation will install ``pip`` if it is not already installed,
but otherwise does nothing. To ensure the installed version of ``pip``
is at least as recent as the one bundled with ``ensurepip``, pass the
``--upgrade`` option::
python -m ensurepip --upgrade
By default, ``pip`` is installed into the current virtual environment
(if one is active) or into the system site packages (if there is no
active virtual environment). The installation location can be controlled
through two additional command line options:
* ``--root <dir>``: Installs ``pip`` relative to the given root directory
rather than the root of the currently active virtual environment (if any)
or the default root for the current Python installation.
* ``--user``: Installs ``pip`` into the user site packages directory rather
than globally for the current Python installation (this option is not
permitted inside an active virtual environment).
By default, the scripts ``pip``, ``pipX``, and ``pipX.Y`` will be installed
(where X.Y stands for the version of Python used to invoke ``ensurepip``). The
scripts installed can be controlled through two additional command line
options:
* ``--altinstall``: if an alternate installation is requested, the ``pip`` and
``pipX`` script will *not* be installed.
* ``--no-default-pip``: if a non-default installation is request, the ``pip``
script will *not* be installed.
.. versionchanged:: 2.7.15
The exit status is non-zero if the command fails.
Module API
----------
:mod:`ensurepip` exposes two functions for programmatic use:
.. function:: version()
Returns a string specifying the bundled version of pip that will be
installed when bootstrapping an environment.
.. function:: bootstrap(root=None, upgrade=False, user=False, \
altinstall=False, default_pip=True, \
verbosity=0)
Bootstraps ``pip`` into the current or designated environment.
*root* specifies an alternative root directory to install relative to.
If *root* is ``None``, then installation uses the default install location
for the current environment.
*upgrade* indicates whether or not to upgrade an existing installation
of an earlier version of ``pip`` to the bundled version.
*user* indicates whether to use the user scheme rather than installing
globally.
By default, the scripts ``pip``, ``pipX``, and ``pipX.Y`` will be installed
(where X.Y stands for the current version of Python).
If *altinstall* is set, then ``pip`` and ``pipX`` will *not* be installed.
If *default_pip* is set to ``False``, then ``pip`` will *not* be installed.
Setting both *altinstall* and *default_pip* will trigger
:exc:`ValueError`.
*verbosity* controls the level of output to :data:`sys.stdout` from the
bootstrapping operation.
.. note::
The bootstrapping process has side effects on both ``sys.path`` and
``os.environ``. Invoking the command line interface in a subprocess
instead allows these side effects to be avoided.
.. note::
The bootstrapping process may install additional modules required by
``pip``, but other software should not assume those dependencies will
always be present by default (as the dependencies may be removed in a
future version of ``pip``).

636
Doc/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

539
Doc/library/exceptions.rst Normal file
View File

@@ -0,0 +1,539 @@
.. _bltin-exceptions:
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 subclassed to define new exceptions;
programmers are encouraged to derive new exceptions from the :exc:`Exception`
class or one of its subclasses, and not from :exc:`BaseException`. More
information on defining exceptions is available in the Python Tutorial under
:ref:`tut-userexceptions`.
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 empty
string when there were no arguments.
.. versionadded:: 2.5
.. attribute:: args
The tuple of arguments given to the exception constructor. Some built-in
exceptions (like :exc:`IOError`) expect a certain number of arguments and
assign a special meaning to the elements of this tuple, while others are
usually called only with a single string giving an error message.
.. 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:: StandardError
The base class for all built-in exceptions except :exc:`StopIteration`,
:exc:`GeneratorExit`, :exc:`KeyboardInterrupt` and :exc:`SystemExit`.
:exc:`StandardError` itself is derived from :exc:`Exception`.
.. exception:: ArithmeticError
The base class for those built-in exceptions that are raised for various
arithmetic errors: :exc:`OverflowError`, :exc:`ZeroDivisionError`,
:exc:`FloatingPointError`.
.. exception:: BufferError
Raised when a :ref:`buffer <bufferobjects>` related operation cannot be
performed.
.. 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:`codecs.lookup`.
.. 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 (see :ref:`attribute-references`) or
assignment fails. (When an object does not support attribute references or
attribute assignments at all, :exc:`TypeError` is raised.)
.. exception:: EOFError
Raised when one of the built-in functions (:func:`input` or :func:`raw_input`)
hits an end-of-file condition (EOF) without reading any data. (N.B.: the
:meth:`file.read` and :meth:`file.readline` methods return an empty string
when they hit EOF.)
.. 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
``--with-fpectl`` option, or the :const:`WANT_SIGFPE_HANDLER` symbol is
defined in the :file:`pyconfig.h` file.
.. exception:: GeneratorExit
Raised when a :term:`generator`\'s :meth:`close` method is called. It
directly inherits from :exc:`BaseException` instead of :exc:`StandardError`
since it is technically not an error.
.. versionadded:: 2.5
.. versionchanged:: 2.6
Changed to inherit from :exc:`BaseException`.
.. 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".
This class is derived from :exc:`EnvironmentError`. See the discussion above
for more information on exception instance attributes.
.. versionchanged:: 2.6
Changed :exc:`socket.error` to use this as a base class.
.. 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.
.. 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.)
.. XXX xref to sequences
.. exception:: KeyError
Raised when a mapping (dictionary) key is not found in the set of existing keys.
.. XXX 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.
Interrupts typed when a built-in function :func:`input` or :func:`raw_input` is
waiting for input also raise this exception. 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.
.. 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 :c:func:`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
.. index:: module: errno
This exception is derived from :exc:`EnvironmentError`. It is raised when a
function returns a system-related error (not for illegal argument types or
other incidental errors). The :attr:`errno` attribute is a numeric error
code from :c:data:`errno`, and the :attr:`strerror` attribute is the
corresponding string, as would be printed by the C function :c:func:`perror`.
See the module :mod:`errno`, which contains names for the error codes defined
by the underlying operating system.
For exceptions that involve a file system path (such as :func:`chdir` or
:func:`unlink`), the exception instance will contain a third attribute,
:attr:`filename`, which is the file name passed to the function.
.. 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) and for most operations with plain integers,
which return a long integer instead. Because of the lack of standardization
of floating point exception handling in C, most floating point operations
also aren't checked.
.. 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.
.. exception:: StopIteration
Raised by an :term:`iterator`\'s :meth:`~iterator.next` method to signal that
there are no further values. This is derived from :exc:`Exception` rather
than :exc:`StandardError`, since this is not considered an error in its
normal application.
.. versionadded:: 2.2
.. exception:: SyntaxError
Raised when the parser encounters a syntax error. This may occur in an
:keyword:`import` statement, in an :keyword:`exec` statement, in a call to the
built-in function :func:`eval` or :func:`input`, or when reading the initial
script or standard input (also interactively).
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:: IndentationError
Base class for syntax errors related to incorrect indentation. This is a
subclass of :exc:`SyntaxError`.
.. exception:: TabError
Raised when indentation contains an inconsistent use of tabs and spaces.
This is a subclass of :exc:`IndentationError`.
.. 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 :c:func:`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.
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:`StandardError`, 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:`os.fork`).
The exception inherits from :exc:`BaseException` instead of :exc:`StandardError`
or :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`.
:exc:`UnicodeError` has attributes that describe the encoding or decoding
error. For example, ``err.object[err.start:err.end]`` gives the particular
invalid input that the codec failed on.
.. attribute:: encoding
The name of the encoding that raised the error.
.. attribute:: reason
A string describing the specific codec error.
.. attribute:: object
The object the codec was attempting to encode or decode.
.. attribute:: start
The first index of invalid data in :attr:`object`.
.. attribute:: end
The index after the last invalid data in :attr:`object`.
.. 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 an 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:: VMSError
Only available on VMS. Raised when a VMS-specific error occurs.
.. exception:: WindowsError
Raised when a Windows-specific error occurs or when the error number does not
correspond to an :c:data:`errno` value. The :attr:`winerror` and
:attr:`strerror` values are created from the return values of the
:c:func:`GetLastError` and :c:func:`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 :c:func:`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
.. exception:: BytesWarning
Base class for warnings related to bytes and bytearray.
.. versionadded:: 2.6
Exception hierarchy
-------------------
The class hierarchy for built-in exceptions is:
.. literalinclude:: ../../Lib/test/exception_hierarchy.txt

167
Doc/library/fcntl.rst Normal file
View File

@@ -0,0 +1,167 @@
:mod:`fcntl` --- The ``fcntl`` and ``ioctl`` system calls
=========================================================
.. module:: fcntl
:platform: Unix
:synopsis: The fcntl() and ioctl() system calls.
.. sectionauthor:: Jaap Vermeulen
.. index::
pair: UNIX; file control
pair: UNIX; I/O control
This module performs file control and I/O control on file descriptors. It is an
interface to the :c:func:`fcntl` and :c:func:`ioctl` Unix routines. For a
complete description of these calls, see :manpage:`fcntl(2)` and
:manpage:`ioctl(2)` Unix manual pages.
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:`~io.IOBase.fileno` which returns a genuine file descriptor.
The module defines the following functions:
.. function:: fcntl(fd, op[, arg])
Perform the operation *op* on file descriptor *fd* (file objects providing
a :meth:`~io.IOBase.fileno` method are accepted as well). The values used
for for *op* are operating system dependent, and are available as constants
in the :mod:`fcntl` module, using the same names as used in the relevant C
header files. 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 :c:func:`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
:c:func:`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 :c:func:`fcntl` fails, an :exc:`IOError` is raised.
.. function:: ioctl(fd, op[, arg[, mutate_flag]])
This function is identical to the :func:`~fcntl.fcntl` function, except that the
operations are typically defined in the library module :mod:`termios` and the
argument handling is even more complicated.
The op parameter is limited to values that can fit in 32-bits.
Additional constants of interest for use as the *op* argument can be
found in the :mod:`termios` module, under the same names as used in
the relevant C header files.
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.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.
If the :c:func:`ioctl` fails, an :exc:`IOError` exception is raised.
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:`~io.IOBase.fileno` method are accepted as well). See the Unix manual
:manpage:`flock(2)` for details. (On some systems, this function is emulated
using :c:func:`fcntl`.)
If the :c:func:`flock` fails, an :exc:`IOError` exception is raised.
.. function:: lockf(fd, operation, [length, [start, [whence]]])
This is essentially a wrapper around the :func:`~fcntl.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
bitwise ORed 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:`io.IOBase.seek`, specifically:
* :const:`0` -- relative to the start of the file (:data:`os.SEEK_SET`)
* :const:`1` -- relative to the current buffer position (:data:`os.SEEK_CUR`)
* :const:`2` -- relative to the end of the file (:data:`os.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 :data:`~os.O_SHLOCK` and :data:`~os.O_EXLOCK` are
present in the :mod:`os` module (on BSD only), the :func:`os.open`
function provides an alternative to the :func:`lockf` and :func:`flock`
functions.

195
Doc/library/filecmp.rst Normal file
View File

@@ -0,0 +1,195 @@
:mod:`filecmp` --- File and Directory Comparisons
=================================================
.. module:: filecmp
:synopsis: Compare files efficiently.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
**Source code:** :source:`Lib/filecmp.py`
--------------
The :mod:`filecmp` module defines functions to compare files and directories,
with various optional time/correctness trade-offs. For comparing files,
see also the :mod:`difflib` module.
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])
Compare the files in the two directories *dir1* and *dir2* whose names are
given by *common*.
Returns three lists of file names: *match*, *mismatch*,
*errors*. *match* contains the list of files that match, *mismatch* contains
the names of those that don't, and *errors* lists the names of files which
could not be compared. Files are listed in *errors* if they don't exist in
one of the directories, the user lacks permission to read them or if the
comparison could not be done for some other reason.
The *shallow* parameter has the same meaning and default value as for
:func:`filecmp.cmp`.
For example, ``cmpfiles('a', 'b', ['c', 'd/e'])`` will compare ``a/c`` with
``b/c`` and ``a/d/e`` with ``b/d/e``. ``'c'`` and ``'d/e'`` will each be in
one of the three returned lists.
Example::
>>> import filecmp
>>> filecmp.cmp('undoc.rst', 'undoc.rst') # doctest: +SKIP
True
>>> filecmp.cmp('undoc.rst', 'index.rst') # doctest: +SKIP
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 compares files by doing *shallow* comparisons
as described for :func:`filecmp.cmp`.
The :class:`dircmp` class provides the following methods:
.. method:: report()
Print (to ``sys.stdout``) a comparison between *a* and *b*.
.. method:: report_partial_closure()
Print a comparison between *a* and *b* and common immediate
subdirectories.
.. method:: report_full_closure()
Print a comparison between *a* and *b* and common subdirectories
(recursively).
The :class:`dircmp` class 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:: left
The directory *a*.
.. attribute:: right
The directory *b*.
.. attribute:: left_list
Files and subdirectories in *a*, filtered by *hide* and *ignore*.
.. attribute:: right_list
Files and subdirectories in *b*, filtered by *hide* and *ignore*.
.. attribute:: common
Files and subdirectories in both *a* and *b*.
.. attribute:: left_only
Files and subdirectories only in *a*.
.. attribute:: right_only
Files and subdirectories only in *b*.
.. attribute:: common_dirs
Subdirectories in both *a* and *b*.
.. attribute:: common_files
Files in both *a* and *b*
.. attribute:: 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:: same_files
Files which are identical in both *a* and *b*, using the class's
file comparison operator.
.. attribute:: diff_files
Files which are in both *a* and *b*, whose contents differ according
to the class's file comparison operator.
.. attribute:: funny_files
Files which are in both *a* and *b*, but could not be compared.
.. attribute:: subdirs
A dictionary mapping names in :attr:`common_dirs` to :class:`dircmp` objects.
Here is a simplified example of using the ``subdirs`` attribute to search
recursively through two directories to show common different files::
>>> from filecmp import dircmp
>>> def print_diff_files(dcmp):
... for name in dcmp.diff_files:
... print "diff_file %s found in %s and %s" % (name, dcmp.left,
... dcmp.right)
... for sub_dcmp in dcmp.subdirs.values():
... print_diff_files(sub_dcmp)
...
>>> dcmp = dircmp('dir1', 'dir2') # doctest: +SKIP
>>> print_diff_files(dcmp) # doctest: +SKIP

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