klarkxy/hustoj
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

增加python文档

Browse Source
This commit is contained in:
klarkxy
2025-03-09 17:10:56 +08:00
parent 7153217140
commit 723430cade
1039 changed files with 699509 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

474
web/python-docs/_sources/library/2to3.rst.txt Normal file
View File

@@ -0,0 +1,474 @@
.. _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:: 3.2.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:: 3.2.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:: 3.2.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 ``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)`` and ``isinstance(x, (int, float, int))`` is converted to
``isinstance(x, (int, float))``.
.. 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:`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:: operator
Converts calls to various functions in the :mod:`operator` module to other,
but equivalent, function calls. When needed, the appropriate ``import``
statements are added, e.g. ``import collections.abc``. The following mapping
are made:
================================== =============================================
From To
================================== =============================================
``operator.isCallable(obj)`` ``callable(obj)``
``operator.sequenceIncludes(obj)`` ``operator.contains(obj)``
``operator.isSequenceType(obj)`` ``isinstance(obj, collections.abc.Sequence)``
``operator.isMappingType(obj)`` ``isinstance(obj, collections.abc.Mapping)``
``operator.isNumberType(obj)`` ``isinstance(obj, numbers.Number)``
``operator.repeat(obj, n)`` ``operator.mul(obj, n)``
``operator.irepeat(obj, n)`` ``operator.imul(obj, n)``
================================== =============================================
.. 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 ``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 3.0.
.. 2to3fixer:: raw_input
Converts :func:`raw_input` to :func:`input`.
.. 2to3fixer:: reduce
Handles the move of :func:`reduce` to :func:`functools.reduce`.
.. 2to3fixer:: reload
Converts :func:`reload` to :func:`importlib.reload`.
.. 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>
**Source code:** :source:`Lib/lib2to3/`
--------------
.. note::
The :mod:`lib2to3` API should be considered unstable and may change
drastically in the future.
.. XXX What is the public interface anyway?

103
web/python-docs/_sources/library/__future__.rst.txt Normal file
View File

@@ -0,0 +1,103 @@
: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 :data:`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* |
+------------------+-------------+--------------+---------------------------------------------+
| generator_stop | 3.5.0b1 | 3.7 | :pep:`479`: |
| | | | *StopIteration handling inside generators* |
+------------------+-------------+--------------+---------------------------------------------+
| annotations | 3.7.0b1 | 3.10 | :pep:`563`: |
| | | | *Postponed evaluation of annotations* |
+------------------+-------------+--------------+---------------------------------------------+
.. XXX Adding a new entry? Remember to update simple_stmts.rst, too.
.. seealso::
:ref:`future`
How the compiler treats future imports.

25
web/python-docs/_sources/library/__main__.rst.txt Normal file
View File

@@ -0,0 +1,25 @@
:mod:`__main__` --- Top-level script environment
================================================
.. module:: __main__
:synopsis: The environment where the top-level script is run.
--------------
``'__main__'`` is the name of the scope in which top-level code executes.
A module's __name__ is set equal to ``'__main__'`` when read from
standard input, a script, or from an interactive prompt.
A module can discover whether or not it is running in the main scope by
checking its own ``__name__``, which allows a common idiom for conditionally
executing code in a module when it is run as a script or with ``python
-m`` but not when it is imported::
if __name__ == "__main__":
# execute only if run as a script
main()
For a package, the same effect can be achieved by including a
``__main__.py`` module, the contents of which will be executed when the
module is run with ``-m``.

22
web/python-docs/_sources/library/_dummy_thread.rst.txt Normal file
View File

@@ -0,0 +1,22 @@
:mod:`_dummy_thread` --- Drop-in replacement for the :mod:`_thread` module
==========================================================================
.. module:: _dummy_thread
:synopsis: Drop-in replacement for the _thread module.
**Source code:** :source:`Lib/_dummy_thread.py`
.. deprecated:: 3.7
Python now always has threading enabled. Please use :mod:`_thread`
(or, better, :mod:`threading`) instead.
--------------
This module provides a duplicate interface to the :mod:`_thread` module.
It was meant to be imported when the :mod:`_thread` module was not provided
on a platform.
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
web/python-docs/_sources/library/_thread.rst.txt Normal file
View File

@@ -0,0 +1,215 @@
:mod:`_thread` --- Low-level threading API
==========================================
.. module:: _thread
:synopsis: Low-level threading API.
.. index::
single: light-weight processes
single: processes, light-weight
single: binary semaphores
single: semaphores, binary
--------------
This module provides low-level primitives for working with multiple threads
(also called :dfn:`light-weight processes` or :dfn:`tasks`) --- multiple threads of
control sharing their global data space. For synchronization, simple locks
(also called :dfn:`mutexes` or :dfn:`binary semaphores`) are provided.
The :mod:`threading` module provides an easier to use and higher-level
threading API built on top of this module.
.. index::
single: pthreads
pair: threads; POSIX
.. versionchanged:: 3.7
This module used to be optional, it is now always available.
This module defines the following constants and functions:
.. exception:: error
Raised on thread-specific errors.
.. versionchanged:: 3.3
This is now a synonym of the built-in :exc:`RuntimeError`.
.. data:: LockType
This is the type of lock objects.
.. function:: start_new_thread(function, args[, kwargs])
Start a new thread and return its identifier. The thread executes the
function *function* with the argument list *args* (which must be a tuple).
The optional *kwargs* argument specifies a dictionary of keyword arguments.
When the function returns, the thread silently exits.
When the function terminates with an unhandled exception,
:func:`sys.unraisablehook` is called to handle the exception. The *object*
attribute of the hook argument is *function*. By default, a stack trace is
printed and then the thread exits (but other threads continue to run).
When the function raises a :exc:`SystemExit` exception, it is silently
ignored.
.. versionchanged:: 3.8
:func:`sys.unraisablehook` is now used to handle unhandled exceptions.
.. function:: interrupt_main()
Simulate the effect of a :data:`signal.SIGINT` signal arriving in the main
thread. A thread can use this function to interrupt the main thread.
If :data:`signal.SIGINT` isn't handled by Python (it was set to
:data:`signal.SIG_DFL` or :data:`signal.SIG_IGN`), this function does
nothing.
.. function:: exit()
Raise the :exc:`SystemExit` exception. When not caught, this will cause the
thread to exit silently.
..
function:: exit_prog(status)
Exit all threads and report the value of the integer argument
*status* as the exit status of the entire program.
**Caveat:** code in pending :keyword:`finally` clauses, in this thread
or in other threads, is not executed.
.. function:: allocate_lock()
Return a new lock object. Methods of locks are described below. The lock is
initially unlocked.
.. function:: get_ident()
Return the 'thread identifier' of the current thread. This is a nonzero
integer. Its value has no direct meaning; it is intended as a magic cookie to
be used e.g. to index a dictionary of thread-specific data. Thread identifiers
may be recycled when a thread exits and another thread is created.
.. function:: get_native_id()
Return the native integral Thread ID of the current thread assigned by the kernel.
This is a non-negative integer.
Its value may be used to uniquely identify this particular thread system-wide
(until the thread terminates, after which the value may be recycled by the OS).
.. availability:: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX.
.. versionadded:: 3.8
.. function:: stack_size([size])
Return the thread stack size used when creating new threads. The optional
*size* argument specifies the stack size to be used for subsequently created
threads, and must be 0 (use platform or configured default) or a positive
integer value of at least 32,768 (32 KiB). If *size* is not specified,
0 is used. If changing the thread stack size is
unsupported, a :exc:`RuntimeError` is raised. If the specified stack size is
invalid, a :exc:`ValueError` is raised and the stack size is unmodified. 32 KiB
is currently the minimum supported stack size value to guarantee sufficient
stack space for the interpreter itself. Note that some platforms may have
particular restrictions on values for the stack size, such as requiring a
minimum stack size > 32 KiB or requiring allocation in multiples of the system
memory page size - platform documentation should be referred to for more
information (4 KiB pages are common; using multiples of 4096 for the stack size is
the suggested approach in the absence of more specific information).
.. availability:: Windows, systems with POSIX threads.
.. data:: TIMEOUT_MAX
The maximum value allowed for the *timeout* parameter of
:meth:`Lock.acquire`. Specifying a timeout greater than this value will
raise an :exc:`OverflowError`.
.. versionadded:: 3.2
Lock objects have the following methods:
.. method:: lock.acquire(waitflag=1, timeout=-1)
Without any optional argument, this method acquires the lock unconditionally, if
necessary waiting until it is released by another thread (only one thread at a
time can acquire a lock --- that's their reason for existence).
If the integer *waitflag* argument is present, the action depends on its
value: if it is zero, the lock is only acquired if it can be acquired
immediately without waiting, while if it is nonzero, the lock is acquired
unconditionally as above.
If the floating-point *timeout* argument is present and positive, it
specifies the maximum wait time in seconds before returning. A negative
*timeout* argument specifies an unbounded wait. You cannot specify
a *timeout* if *waitflag* is zero.
The return value is ``True`` if the lock is acquired successfully,
``False`` if not.
.. versionchanged:: 3.2
The *timeout* parameter is new.
.. versionchanged:: 3.2
Lock acquires can now be interrupted by signals on POSIX.
.. method:: lock.release()
Releases the lock. The lock must have been acquired earlier, but not
necessarily by the same thread.
.. method:: lock.locked()
Return the status of the lock: ``True`` if it has been acquired by some thread,
``False`` if not.
In addition to these methods, lock objects can also be used via the
:keyword:`with` statement, e.g.::
import _thread
a_lock = _thread.allocate_lock()
with a_lock:
print("a_lock is locked while this executes")
**Caveats:**
.. index:: module: signal
* Threads interact strangely with interrupts: the :exc:`KeyboardInterrupt`
exception will be received by an arbitrary thread. (When the :mod:`signal`
module is available, interrupts always go to the main thread.)
* Calling :func:`sys.exit` or raising the :exc:`SystemExit` exception is
equivalent to calling :func:`_thread.exit`.
* It is not possible to interrupt the :meth:`acquire` method on a lock --- the
:exc:`KeyboardInterrupt` exception will happen after the lock has been acquired.
* When the main thread exits, it is system defined whether the other threads
survive. On most systems, they are killed without executing
:keyword:`try` ... :keyword:`finally` clauses or executing object
destructors.
* When the main thread exits, it does not do any of its usual cleanup (except
that :keyword:`try` ... :keyword:`finally` clauses are honored), and the
standard I/O files are not flushed.

342
web/python-docs/_sources/library/abc.rst.txt Normal file
View File

@@ -0,0 +1,342 @@
: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
**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.abc` submodule 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 metaclass :class:`ABCMeta` for defining ABCs and
a helper class :class:`ABC` to alternatively define ABCs through inheritance:
.. class:: ABC
A helper class that has :class:`ABCMeta` as its metaclass. With this class,
an abstract base class can be created by simply deriving from :class:`ABC`
avoiding sometimes confusing metaclass usage, for example::
from abc import ABC
class MyABC(ABC):
pass
Note that the type of :class:`ABC` is still :class:`ABCMeta`, therefore
inheriting from :class:`ABC` requires the usual precautions regarding
metaclass usage, as multiple inheritance may lead to metaclass conflicts.
One may also define an abstract base class by passing the metaclass
keyword and using :class:`ABCMeta` directly, for example::
from abc import ABCMeta
class MyABC(metaclass=ABCMeta):
pass
.. versionadded:: 3.4
.. 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 ABC
class MyABC(ABC):
pass
MyABC.register(tuple)
assert issubclass(tuple, MyABC)
assert isinstance((), MyABC)
.. versionchanged:: 3.3
Returns the registered subclass, to allow usage as a class decorator.
.. versionchanged:: 3.4
To detect calls to :meth:`register`, you can use the
:func:`get_cache_token` function.
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:
def __getitem__(self, index):
...
def __len__(self):
...
def get_iterator(self):
return iter(self)
class MyIterable(ABC):
@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.
The :mod:`abc` module also provides the following decorator:
.. decorator:: abstractmethod
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. :func:`abstractmethod` may be used
to declare abstract methods for properties and descriptors.
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.
When :func:`abstractmethod` is applied in combination with other method
descriptors, it should be applied as the innermost decorator, as shown in
the following usage examples::
class C(ABC):
@abstractmethod
def my_abstract_method(self, ...):
...
@classmethod
@abstractmethod
def my_abstract_classmethod(cls, ...):
...
@staticmethod
@abstractmethod
def my_abstract_staticmethod(...):
...
@property
@abstractmethod
def my_abstract_property(self):
...
@my_abstract_property.setter
@abstractmethod
def my_abstract_property(self, val):
...
@abstractmethod
def _get_x(self):
...
@abstractmethod
def _set_x(self, val):
...
x = property(_get_x, _set_x)
In order to correctly interoperate with the abstract base class machinery,
the descriptor must identify itself as abstract using
:attr:`__isabstractmethod__`. In general, this attribute should be ``True``
if any of the methods used to compose the descriptor are abstract. For
example, Python's built-in :class:`property` does the equivalent of::
class Descriptor:
...
@property
def __isabstractmethod__(self):
return any(getattr(f, '__isabstractmethod__', False) for
f in (self._fget, self._fset, self._fdel))
.. 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.
The :mod:`abc` module also supports the following legacy decorators:
.. decorator:: abstractclassmethod
.. versionadded:: 3.2
.. deprecated:: 3.3
It is now possible to use :class:`classmethod` with
:func:`abstractmethod`, making this decorator redundant.
A subclass of the built-in :func:`classmethod`, indicating an abstract
classmethod. Otherwise it is similar to :func:`abstractmethod`.
This special case is deprecated, as the :func:`classmethod` decorator
is now correctly identified as abstract when applied to an abstract
method::
class C(ABC):
@classmethod
@abstractmethod
def my_abstract_classmethod(cls, ...):
...
.. decorator:: abstractstaticmethod
.. versionadded:: 3.2
.. deprecated:: 3.3
It is now possible to use :class:`staticmethod` with
:func:`abstractmethod`, making this decorator redundant.
A subclass of the built-in :func:`staticmethod`, indicating an abstract
staticmethod. Otherwise it is similar to :func:`abstractmethod`.
This special case is deprecated, as the :func:`staticmethod` decorator
is now correctly identified as abstract when applied to an abstract
method::
class C(ABC):
@staticmethod
@abstractmethod
def my_abstract_staticmethod(...):
...
.. decorator:: abstractproperty
.. deprecated:: 3.3
It is now possible to use :class:`property`, :meth:`property.getter`,
:meth:`property.setter` and :meth:`property.deleter` with
:func:`abstractmethod`, making this decorator redundant.
A subclass of the built-in :func:`property`, indicating an abstract
property.
This special case is deprecated, as the :func:`property` decorator
is now correctly identified as abstract when applied to an abstract
method::
class C(ABC):
@property
@abstractmethod
def my_abstract_property(self):
...
The above example defines a read-only property; you can also define a
read-write abstract property by appropriately marking one or more of the
underlying methods as abstract::
class C(ABC):
@property
def x(self):
...
@x.setter
@abstractmethod
def x(self, val):
...
If only some components are abstract, only those components need to be
updated to create a concrete property in a subclass::
class D(C):
@C.x.setter
def x(self, val):
...
The :mod:`abc` module also provides the following functions:
.. function:: get_cache_token()
Returns the current abstract base class cache token.
The token is an opaque object (that supports equality testing) identifying
the current version of the abstract base class cache for virtual subclasses.
The token changes with every call to :meth:`ABCMeta.register` on any ABC.
.. versionadded:: 3.4
.. rubric:: Footnotes
.. [#] C++ programmers should note that Python's virtual base class
concept is not the same as C++'s.

241
web/python-docs/_sources/library/aifc.rst.txt Normal file
View File

@@ -0,0 +1,241 @@
:mod:`aifc` --- Read and write AIFF and AIFC files
==================================================
.. module:: aifc
:synopsis: Read and write audio files in AIFF or AIFC format.
**Source code:** :source:`Lib/aifc.py`
.. index::
single: Audio Interchange File Format
single: AIFF
single: AIFF-C
--------------
This module provides support for reading and writing AIFF and AIFF-C files.
AIFF is Audio Interchange File Format, a format for storing digital audio
samples in a file. AIFF-C is a newer version of the format that includes the
ability to compress the audio data.
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=None)
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
:term:`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`.
The :func:`.open` function may be used in a :keyword:`with` statement. When
the :keyword:`!with` block completes, the :meth:`~aifc.close` method is called.
.. versionchanged:: 3.4
Support for the :keyword:`with` statement was added.
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 bytes array of length 4 describing the type of compression
used in the audio file. For AIFF files, the returned value is
``b'NONE'``.
.. method:: aifc.getcompname()
Return a bytes array convertible to a human-readable description
of the type of compression used in the audio file. For AIFF files,
the returned value is ``b'not compressed'``.
.. method:: aifc.getparams()
Returns a :func:`~collections.namedtuple` ``(nchannels, sampwidth,
framerate, nframes, comptype, compname)``, equivalent to output of the
:meth:`get\*` methods.
.. 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 as a bytes array, the type parameter should be a
bytes array of length 4. Currently the following compression types
are supported: ``b'NONE'``, ``b'ULAW'``, ``b'ALAW'``, ``b'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()
:noindex:
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.
.. versionchanged:: 3.4
Any :term:`bytes-like object` is now accepted.
.. method:: aifc.writeframesraw(data)
Like :meth:`writeframes`, except that the header of the audio file is not
updated.
.. versionchanged:: 3.4
Any :term:`bytes-like object` is now accepted.
.. method:: aifc.close()
:noindex:
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.

29
web/python-docs/_sources/library/allos.rst.txt Normal file
View File

@@ -0,0 +1,29 @@
.. _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
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

20
web/python-docs/_sources/library/archiving.rst.txt Normal file
View File

@@ -0,0 +1,20 @@
.. _archiving:
******************************
Data Compression and Archiving
******************************
The modules described in this chapter support data compression with the zlib,
gzip, bzip2 and lzma 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
lzma.rst
zipfile.rst
tarfile.rst

2115
web/python-docs/_sources/library/argparse.rst.txt Normal file
View File

File diff suppressed because it is too large Load Diff

275
web/python-docs/_sources/library/array.rst.txt Normal file
View File

@@ -0,0 +1,275 @@
: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 | Notes |
+===========+====================+===================+=======================+=======+
| ``'b'`` | signed char | int | 1 | |
+-----------+--------------------+-------------------+-----------------------+-------+
| ``'B'`` | unsigned char | int | 1 | |
+-----------+--------------------+-------------------+-----------------------+-------+
| ``'u'`` | Py_UNICODE | Unicode character | 2 | \(1) |
+-----------+--------------------+-------------------+-----------------------+-------+
| ``'h'`` | signed short | int | 2 | |
+-----------+--------------------+-------------------+-----------------------+-------+
| ``'H'`` | unsigned short | int | 2 | |
+-----------+--------------------+-------------------+-----------------------+-------+
| ``'i'`` | signed int | int | 2 | |
+-----------+--------------------+-------------------+-----------------------+-------+
| ``'I'`` | unsigned int | int | 2 | |
+-----------+--------------------+-------------------+-----------------------+-------+
| ``'l'`` | signed long | int | 4 | |
+-----------+--------------------+-------------------+-----------------------+-------+
| ``'L'`` | unsigned long | int | 4 | |
+-----------+--------------------+-------------------+-----------------------+-------+
| ``'q'`` | signed long long | int | 8 | |
+-----------+--------------------+-------------------+-----------------------+-------+
| ``'Q'`` | unsigned long long | int | 8 | |
+-----------+--------------------+-------------------+-----------------------+-------+
| ``'f'`` | float | float | 4 | |
+-----------+--------------------+-------------------+-----------------------+-------+
| ``'d'`` | double | float | 8 | |
+-----------+--------------------+-------------------+-----------------------+-------+
Notes:
(1)
The ``'u'`` type code corresponds to Python's obsolete unicode character
(:c:type:`Py_UNICODE` which is :c:type:`wchar_t`). Depending on the
platform, it can be 16 bits or 32 bits.
``'u'`` will be removed together with the rest of the :c:type:`Py_UNICODE`
API.
.. deprecated-removed:: 3.3 4.0
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 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, a
:term:`bytes-like object`, or iterable over elements of the
appropriate type.
If given a list or string, the initializer is passed to the new array's
:meth:`fromlist`, :meth:`frombytes`, or :meth:`fromunicode` method (see below)
to add initial items to the array. Otherwise, the iterable initializer is
passed to the :meth:`extend` method.
.. audit-event:: array.__new__ typecode,initializer array.array
.. data:: typecodes
A string with all available type codes.
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 :term:`bytes-like objects <bytes-like object>` 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.
.. method:: array.frombytes(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).
.. versionadded:: 3.2
:meth:`fromstring` is renamed to :meth:`frombytes` for clarity.
.. method:: array.fromfile(f, n)
Read *n* items (as machine values) from the :term:`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.
.. 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()
Deprecated alias for :meth:`frombytes`.
.. deprecated-removed:: 3.2 3.9
.. 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.frombytes(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.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.tobytes()
Convert the array to an array of machine values and return the bytes
representation (the same sequence of bytes that would be written to a file by
the :meth:`tofile` method.)
.. versionadded:: 3.2
:meth:`tostring` is renamed to :meth:`tobytes` for clarity.
.. method:: array.tofile(f)
Write all items (as machine values) to the :term:`file object` *f*.
.. method:: array.tolist()
Convert the array to an ordinary list with the same items.
.. method:: array.tostring()
Deprecated alias for :meth:`tobytes`.
.. deprecated-removed:: 3.2 3.9
.. 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.tobytes().decode(enc)`` to
obtain a unicode string from an array of some other type.
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 ``'u'``, 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('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.

366
web/python-docs/_sources/library/ast.rst.txt Normal file
View File

@@ -0,0 +1,366 @@
: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>
**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.
.. index:: single: ? (question mark); in AST grammar
.. index:: single: * (asterisk); in AST grammar
.. 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
end_lineno
end_col_offset
Instances of :class:`ast.expr` and :class:`ast.stmt` subclasses have
:attr:`lineno`, :attr:`col_offset`, :attr:`lineno`, and :attr:`col_offset`
attributes. The :attr:`lineno` and :attr:`end_lineno` are the first and
last line numbers of source text span (1-indexed so the first line is line 1)
and the :attr:`col_offset` and :attr:`end_col_offset` are the corresponding
UTF-8 byte offsets of the first and last tokens that generated the node.
The UTF-8 offset is recorded because the parser uses UTF-8 internally.
Note that the end positions are not required by the compiler and are
therefore optional. The end offset is *after* the last symbol, for example
one can get the source segment of a one-line expression node using
``source_line[node.col_offset : node.end_col_offset]``.
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.Constant()
node.operand.value = 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.Constant(5, lineno=0, col_offset=0),
lineno=0, col_offset=0)
.. versionchanged:: 3.8
Class :class:`ast.Constant` is now used for all constants.
.. deprecated:: 3.8
Old classes :class:`ast.Num`, :class:`ast.Str`, :class:`ast.Bytes`,
:class:`ast.NameConstant` and :class:`ast.Ellipsis` are still available,
but they will be removed in future Python releases. In the meanwhile,
instantiating them will return an instance of a different class.
.. _abstract-grammar:
Abstract Grammar
----------------
The abstract grammar is currently defined as follows:
.. literalinclude:: ../../Parser/Python.asdl
:language: none
:mod:`ast` Helpers
------------------
Apart from the node classes, the :mod:`ast` module defines these utility functions
and classes for traversing abstract syntax trees:
.. function:: parse(source, filename='<unknown>', mode='exec', *, type_comments=False, feature_version=None)
Parse the source into an AST node. Equivalent to ``compile(source,
filename, mode, ast.PyCF_ONLY_AST)``.
If ``type_comments=True`` is given, the parser is modified to check
and return type comments as specified by :pep:`484` and :pep:`526`.
This is equivalent to adding :data:`ast.PyCF_TYPE_COMMENTS` to the
flags passed to :func:`compile()`. This will report syntax errors
for misplaced type comments. Without this flag, type comments will
be ignored, and the ``type_comment`` field on selected AST nodes
will always be ``None``. In addition, the locations of ``# type:
ignore`` comments will be returned as the ``type_ignores``
attribute of :class:`Module` (otherwise it is always an empty list).
In addition, if ``mode`` is ``'func_type'``, the input syntax is
modified to correspond to :pep:`484` "signature type comments",
e.g. ``(str, int) -> List[str]``.
Also, setting ``feature_version`` to a tuple ``(major, minor)``
will attempt to parse using that Python version's grammar.
Currently ``major`` must equal to ``3``. For example, setting
``feature_version=(3, 4)`` will allow the use of ``async`` and
``await`` as variable names. The lowest supported version is
``(3, 4)``; the highest is ``sys.version_info[0:2]``.
.. 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.
.. versionchanged:: 3.8
Added ``type_comments``, ``mode='func_type'`` and ``feature_version``.
.. function:: literal_eval(node_or_string)
Safely evaluate an expression node or a string containing a Python literal or
container display. The string or node provided may only consist of the
following Python literal structures: strings, bytes, numbers, tuples, lists,
dicts, sets, 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.
.. versionchanged:: 3.2
Now allows bytes and set literals.
.. function:: get_docstring(node, clean=True)
Return the docstring of the given *node* (which must be a
:class:`FunctionDef`, :class:`AsyncFunctionDef`, :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`.
.. versionchanged:: 3.5
:class:`AsyncFunctionDef` is now supported.
.. function:: get_source_segment(source, node, *, padded=False)
Get source code segment of the *source* that generated *node*.
If some location information (:attr:`lineno`, :attr:`end_lineno`,
:attr:`col_offset`, or :attr:`end_col_offset`) is missing, return ``None``.
If *padded* is ``True``, the first line of a multi-line statement will
be padded with spaces to match its original position.
.. versionadded:: 3.8
.. 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 and end 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`, :attr:`col_offset`, :attr:`end_lineno`,
and :attr:`end_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.
.. deprecated:: 3.8
Methods :meth:`visit_Num`, :meth:`visit_Str`, :meth:`visit_Bytes`,
:meth:`visit_NameConstant` and :meth:`visit_Ellipsis` are deprecated
now and will not be called in future Python versions. Add the
:meth:`visit_Constant` method to handle all constant nodes.
.. 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 Subscript(
value=Name(id='data', ctx=Load()),
slice=Index(value=Constant(value=node.id)),
ctx=node.ctx
)
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.
If :class:`NodeTransformer` introduces new nodes (that weren't part of
original tree) without giving them location information (such as
:attr:`lineno`), :func:`fix_missing_locations` should be called with
the new sub-tree to recalculate the location information::
tree = ast.parse('foo', mode='eval')
new_tree = fix_missing_locations(RewriteName().visit(tree))
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. If *annotate_fields* is true (by default),
the returned string will show the names and the values for fields.
If *annotate_fields* is false, the result string will be more compact by
omitting unambiguous field names. Attributes such as line
numbers and column offsets are not dumped by default. If this is wanted,
*include_attributes* can be set to true.
.. seealso::
`Green Tree Snakes <https://greentreesnakes.readthedocs.io/>`_, an external
documentation resource, has good details on working with Python ASTs.
`ASTTokens <https://asttokens.readthedocs.io/en/latest/user-guide.html>`_
annotates Python ASTs with the positions of tokens and text in the source
code that generated them. This is helpful for tools that make source code
transformations.
`leoAst.py <http://leoeditor.com/appendices.html#leoast-py>`_ unifies the
token-based and parse-tree-based views of python programs by inserting
two-way links between tokens and ast nodes.
`LibCST <https://libcst.readthedocs.io/>`_ parses code as a Concrete Syntax
Tree that looks like an ast tree and keeps all formatting details. It's
useful for building automated refactoring (codemod) applications and
linters.
`Parso <https://parso.readthedocs.io>`_ is a Python parser that supports
error recovery and round-trip parsing for different Python versions (in
multiple Python versions). Parso is also able to list multiple syntax errors
in your python file.

213
web/python-docs/_sources/library/asynchat.rst.txt Normal file
View File

@@ -0,0 +1,213 @@
: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`
.. deprecated:: 3.6
Please use :mod:`asyncio` instead.
--------------
.. note::
This module exists for backwards compatibility only. For new code we
recommend using :mod:`asyncio`.
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 :abbr:`FIFO (first-in, first-out)` queue 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 bytes object. At this point
the :class:`async_chat` object removes the producer from the queue and starts
using the next producer, if any. When the producer queue 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 queue. When this producer is popped off
the queue 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 queue.
.. 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 queue 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 queue 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-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. ::
import asynchat
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 = b""
self.set_terminator(b"\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(b"".join(self.ibuffer))
self.ibuffer = []
if self.op.upper() == b"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, b"".join(self.ibuffer))
self.handling = True
self.ibuffer = []
self.handle_request()

218
web/python-docs/_sources/library/asyncio-api-index.rst.txt Normal file
View File

@@ -0,0 +1,218 @@
.. currentmodule:: asyncio
====================
High-level API Index
====================
This page lists all high-level async/await enabled asyncio APIs.
Tasks
=====
Utilities to run asyncio programs, create Tasks, and
await on multiple things with timeouts.
.. list-table::
:widths: 50 50
:class: full-width-table
* - :func:`run`
- Create event loop, run a coroutine, close the loop.
* - :func:`create_task`
- Start an asyncio Task.
* - ``await`` :func:`sleep`
- Sleep for a number of seconds.
* - ``await`` :func:`gather`
- Schedule and wait for things concurrently.
* - ``await`` :func:`wait_for`
- Run with a timeout.
* - ``await`` :func:`shield`
- Shield from cancellation.
* - ``await`` :func:`wait`
- Monitor for completion.
* - :func:`current_task`
- Return the current Task.
* - :func:`all_tasks`
- Return all tasks for an event loop.
* - :class:`Task`
- Task object.
* - :func:`run_coroutine_threadsafe`
- Schedule a coroutine from another OS thread.
* - ``for in`` :func:`as_completed`
- Monitor for completion with a ``for`` loop.
.. rubric:: Examples
* :ref:`Using asyncio.gather() to run things in parallel
<asyncio_example_gather>`.
* :ref:`Using asyncio.wait_for() to enforce a timeout
<asyncio_example_waitfor>`.
* :ref:`Cancellation <asyncio_example_task_cancel>`.
* :ref:`Using asyncio.sleep() <asyncio_example_sleep>`.
* See also the main :ref:`Tasks documentation page <coroutine>`.
Queues
======
Queues should be used to distribute work amongst multiple asyncio Tasks,
implement connection pools, and pub/sub patterns.
.. list-table::
:widths: 50 50
:class: full-width-table
* - :class:`Queue`
- A FIFO queue.
* - :class:`PriorityQueue`
- A priority queue.
* - :class:`LifoQueue`
- A LIFO queue.
.. rubric:: Examples
* :ref:`Using asyncio.Queue to distribute workload between several
Tasks <asyncio_example_queue_dist>`.
* See also the :ref:`Queues documentation page <asyncio-queues>`.
Subprocesses
============
Utilities to spawn subprocesses and run shell commands.
.. list-table::
:widths: 50 50
:class: full-width-table
* - ``await`` :func:`create_subprocess_exec`
- Create a subprocess.
* - ``await`` :func:`create_subprocess_shell`
- Run a shell command.
.. rubric:: Examples
* :ref:`Executing a shell command <asyncio_example_subprocess_shell>`.
* See also the :ref:`subprocess APIs <asyncio-subprocess>`
documentation.
Streams
=======
High-level APIs to work with network IO.
.. list-table::
:widths: 50 50
:class: full-width-table
* - ``await`` :func:`open_connection`
- Establish a TCP connection.
* - ``await`` :func:`open_unix_connection`
- Establish a Unix socket connection.
* - ``await`` :func:`start_server`
- Start a TCP server.
* - ``await`` :func:`start_unix_server`
- Start a Unix socket server.
* - :class:`StreamReader`
- High-level async/await object to receive network data.
* - :class:`StreamWriter`
- High-level async/await object to send network data.
.. rubric:: Examples
* :ref:`Example TCP client <asyncio_example_stream>`.
* See also the :ref:`streams APIs <asyncio-streams>`
documentation.
Synchronization
===============
Threading-like synchronization primitives that can be used in Tasks.
.. list-table::
:widths: 50 50
:class: full-width-table
* - :class:`Lock`
- A mutex lock.
* - :class:`Event`
- An event object.
* - :class:`Condition`
- A condition object.
* - :class:`Semaphore`
- A semaphore.
* - :class:`BoundedSemaphore`
- A bounded semaphore.
.. rubric:: Examples
* :ref:`Using asyncio.Event <asyncio_example_sync_event>`.
* See also the documentation of asyncio
:ref:`synchronization primitives <asyncio-sync>`.
Exceptions
==========
.. list-table::
:widths: 50 50
:class: full-width-table
* - :exc:`asyncio.TimeoutError`
- Raised on timeout by functions like :func:`wait_for`.
Keep in mind that ``asyncio.TimeoutError`` is **unrelated**
to the built-in :exc:`TimeoutError` exception.
* - :exc:`asyncio.CancelledError`
- Raised when a Task is cancelled. See also :meth:`Task.cancel`.
.. rubric:: Examples
* :ref:`Handling CancelledError to run code on cancellation request
<asyncio_example_task_cancel>`.
* See also the full list of
:ref:`asyncio-specific exceptions <asyncio-exceptions>`.

247
web/python-docs/_sources/library/asyncio-dev.rst.txt Normal file
View File

@@ -0,0 +1,247 @@
.. currentmodule:: asyncio
.. _asyncio-dev:
=======================
Developing with asyncio
=======================
Asynchronous programming is different from classic "sequential"
programming.
This page lists common mistakes and traps and explains how
to avoid them.
.. _asyncio-debug-mode:
Debug Mode
==========
By default asyncio runs in production mode. In order to ease
the development asyncio has a *debug mode*.
There are several ways to enable asyncio debug mode:
* Setting the :envvar:`PYTHONASYNCIODEBUG` environment variable to ``1``.
* Using the :option:`-X` ``dev`` Python command line option.
* Passing ``debug=True`` to :func:`asyncio.run`.
* Calling :meth:`loop.set_debug`.
In addition to enabling the debug mode, consider also:
* setting the log level of the :ref:`asyncio logger <asyncio-logger>` to
:py:data:`logging.DEBUG`, for example the following snippet of code
can be run at startup of the application::
logging.basicConfig(level=logging.DEBUG)
* configuring the :mod:`warnings` module to display
:exc:`ResourceWarning` warnings. One way of doing that is by
using the :option:`-W` ``default`` command line option.
When the debug mode is enabled:
* asyncio checks for :ref:`coroutines that were not awaited
<asyncio-coroutine-not-scheduled>` and logs them; this mitigates
the "forgotten await" pitfall.
* Many non-threadsafe asyncio APIs (such as :meth:`loop.call_soon` and
:meth:`loop.call_at` methods) raise an exception if they are called
from a wrong thread.
* The execution time of the I/O selector is logged if it takes too long to
perform an I/O operation.
* Callbacks taking longer than 100ms are logged. The
:attr:`loop.slow_callback_duration` attribute can be used to set the
minimum execution duration in seconds that is considered "slow".
.. _asyncio-multithreading:
Concurrency and Multithreading
==============================
An event loop runs in a thread (typically the main thread) and executes
all callbacks and Tasks in its thread. While a Task is running in the
event loop, no other Tasks can run in the same thread. When a Task
executes an ``await`` expression, the running Task gets suspended, and
the event loop executes the next Task.
To schedule a :term:`callback` from another OS thread, the
:meth:`loop.call_soon_threadsafe` method should be used. Example::
loop.call_soon_threadsafe(callback, *args)
Almost all asyncio objects are not thread safe, which is typically
not a problem unless there is code that works with them from outside
of a Task or a callback. If there's a need for such code to call a
low-level asyncio API, the :meth:`loop.call_soon_threadsafe` method
should be used, e.g.::
loop.call_soon_threadsafe(fut.cancel)
To schedule a coroutine object from a different OS thread, the
:func:`run_coroutine_threadsafe` function should be used. It returns a
:class:`concurrent.futures.Future` to access the result::
async def coro_func():
return await asyncio.sleep(1, 42)
# Later in another OS thread:
future = asyncio.run_coroutine_threadsafe(coro_func(), loop)
# Wait for the result:
result = future.result()
To handle signals and to execute subprocesses, the event loop must be
run in the main thread.
The :meth:`loop.run_in_executor` method can be used with a
:class:`concurrent.futures.ThreadPoolExecutor` to execute
blocking code in a different OS thread without blocking the OS thread
that the event loop runs in.
There is currently no way to schedule coroutines or callbacks directly
from a different process (such as one started with
:mod:`multiprocessing`). The :ref:`Event Loop Methods <asyncio-event-loop>`
section lists APIs that can read from pipes and watch file descriptors
without blocking the event loop. In addition, asyncio's
:ref:`Subprocess <asyncio-subprocess>` APIs provide a way to start a
process and communicate with it from the event loop. Lastly, the
aforementioned :meth:`loop.run_in_executor` method can also be used
with a :class:`concurrent.futures.ProcessPoolExecutor` to execute
code in a different process.
.. _asyncio-handle-blocking:
Running Blocking Code
=====================
Blocking (CPU-bound) code should not be called directly. For example,
if a function performs a CPU-intensive calculation for 1 second,
all concurrent asyncio Tasks and IO operations would be delayed
by 1 second.
An executor can be used to run a task in a different thread or even in
a different process to avoid blocking the OS thread with the
event loop. See the :meth:`loop.run_in_executor` method for more
details.
.. _asyncio-logger:
Logging
=======
asyncio uses the :mod:`logging` module and all logging is performed
via the ``"asyncio"`` logger.
The default log level is :py:data:`logging.INFO`, which can be easily
adjusted::
logging.getLogger("asyncio").setLevel(logging.WARNING)
.. _asyncio-coroutine-not-scheduled:
Detect never-awaited coroutines
===============================
When a coroutine function is called, but not awaited
(e.g. ``coro()`` instead of ``await coro()``)
or the coroutine is not scheduled with :meth:`asyncio.create_task`, asyncio
will emit a :exc:`RuntimeWarning`::
import asyncio
async def test():
print("never scheduled")
async def main():
test()
asyncio.run(main())
Output::
test.py:7: RuntimeWarning: coroutine 'test' was never awaited
test()
Output in debug mode::
test.py:7: RuntimeWarning: coroutine 'test' was never awaited
Coroutine created at (most recent call last)
File "../t.py", line 9, in <module>
asyncio.run(main(), debug=True)
< .. >
File "../t.py", line 7, in main
test()
test()
The usual fix is to either await the coroutine or call the
:meth:`asyncio.create_task` function::
async def main():
await test()
Detect never-retrieved exceptions
=================================
If a :meth:`Future.set_exception` is called but the Future object is
never awaited on, the exception would never be propagated to the
user code. In this case, asyncio would emit a log message when the
Future object is garbage collected.
Example of an unhandled exception::
import asyncio
async def bug():
raise Exception("not consumed")
async def main():
asyncio.create_task(bug())
asyncio.run(main())
Output::
Task exception was never retrieved
future: <Task finished coro=<bug() done, defined at test.py:3>
exception=Exception('not consumed')>
Traceback (most recent call last):
File "test.py", line 4, in bug
raise Exception("not consumed")
Exception: not consumed
:ref:`Enable the debug mode <asyncio-debug-mode>` to get the
traceback where the task was created::
asyncio.run(main(), debug=True)
Output in debug mode::
Task exception was never retrieved
future: <Task finished coro=<bug() done, defined at test.py:3>
exception=Exception('not consumed') created at asyncio/tasks.py:321>
source_traceback: Object created at (most recent call last):
File "../t.py", line 9, in <module>
asyncio.run(main(), debug=True)
< .. >
Traceback (most recent call last):
File "../t.py", line 4, in bug
raise Exception("not consumed")
Exception: not consumed

1696
web/python-docs/_sources/library/asyncio-eventloop.rst.txt Normal file
View File

File diff suppressed because it is too large Load Diff

77
web/python-docs/_sources/library/asyncio-exceptions.rst.txt Normal file
View File

@@ -0,0 +1,77 @@
.. currentmodule:: asyncio
.. _asyncio-exceptions:
==========
Exceptions
==========
**Source code:** :source:`Lib/asyncio/exceptions.py`
----------------------------------------------------
.. exception:: TimeoutError
The operation has exceeded the given deadline.
.. important::
This exception is different from the builtin :exc:`TimeoutError`
exception.
.. exception:: CancelledError
The operation has been cancelled.
This exception can be caught to perform custom operations
when asyncio Tasks are cancelled. In almost all situations the
exception must be re-raised.
.. versionchanged:: 3.8
:exc:`CancelledError` is now a subclass of :class:`BaseException`.
.. exception:: InvalidStateError
Invalid internal state of :class:`Task` or :class:`Future`.
Can be raised in situations like setting a result value for a
*Future* object that already has a result value set.
.. exception:: SendfileNotAvailableError
The "sendfile" syscall is not available for the given
socket or file type.
A subclass of :exc:`RuntimeError`.
.. exception:: IncompleteReadError
The requested read operation did not complete fully.
Raised by the :ref:`asyncio stream APIs<asyncio-streams>`.
This exception is a subclass of :exc:`EOFError`.
.. attribute:: expected
The total number (:class:`int`) of expected bytes.
.. attribute:: partial
A string of :class:`bytes` read before the end of stream was reached.
.. exception:: LimitOverrunError
Reached the buffer size limit while looking for a separator.
Raised by the :ref:`asyncio stream APIs <asyncio-streams>`.
.. attribute:: consumed
The total number of to be consumed bytes.

257
web/python-docs/_sources/library/asyncio-future.rst.txt Normal file
View File

@@ -0,0 +1,257 @@
.. currentmodule:: asyncio
.. _asyncio-futures:
=======
Futures
=======
**Source code:** :source:`Lib/asyncio/futures.py`,
:source:`Lib/asyncio/base_futures.py`
-------------------------------------
*Future* objects are used to bridge **low-level callback-based code**
with high-level async/await code.
Future Functions
================
.. function:: isfuture(obj)
Return ``True`` if *obj* is either of:
* an instance of :class:`asyncio.Future`,
* an instance of :class:`asyncio.Task`,
* a Future-like object with a ``_asyncio_future_blocking``
attribute.
.. versionadded:: 3.5
.. function:: ensure_future(obj, *, loop=None)
Return:
* *obj* argument as is, if *obj* is a :class:`Future`,
a :class:`Task`, or a Future-like object (:func:`isfuture`
is used for the test.)
* a :class:`Task` object wrapping *obj*, if *obj* is a
coroutine (:func:`iscoroutine` is used for the test);
in this case the coroutine will be scheduled by
``ensure_future()``.
* a :class:`Task` object that would await on *obj*, if *obj* is an
awaitable (:func:`inspect.isawaitable` is used for the test.)
If *obj* is neither of the above a :exc:`TypeError` is raised.
.. important::
See also the :func:`create_task` function which is the
preferred way for creating new Tasks.
.. versionchanged:: 3.5.1
The function accepts any :term:`awaitable` object.
.. function:: wrap_future(future, *, loop=None)
Wrap a :class:`concurrent.futures.Future` object in a
:class:`asyncio.Future` object.
Future Object
=============
.. class:: Future(*, loop=None)
A Future represents an eventual result of an asynchronous
operation. Not thread-safe.
Future is an :term:`awaitable` object. Coroutines can await on
Future objects until they either have a result or an exception
set, or until they are cancelled.
Typically Futures are used to enable low-level
callback-based code (e.g. in protocols implemented using asyncio
:ref:`transports <asyncio-transports-protocols>`)
to interoperate with high-level async/await code.
The rule of thumb is to never expose Future objects in user-facing
APIs, and the recommended way to create a Future object is to call
:meth:`loop.create_future`. This way alternative event loop
implementations can inject their own optimized implementations
of a Future object.
.. versionchanged:: 3.7
Added support for the :mod:`contextvars` module.
.. method:: result()
Return the result of the Future.
If the Future is *done* and has a result set by the
:meth:`set_result` method, the result value is returned.
If the Future is *done* and has an exception set by the
:meth:`set_exception` method, this method raises the exception.
If the Future has been *cancelled*, this method raises
a :exc:`CancelledError` exception.
If the Future's result isn't yet available, this method raises
a :exc:`InvalidStateError` exception.
.. method:: set_result(result)
Mark the Future as *done* and set its result.
Raises a :exc:`InvalidStateError` error if the Future is
already *done*.
.. method:: set_exception(exception)
Mark the Future as *done* and set an exception.
Raises a :exc:`InvalidStateError` error if the Future is
already *done*.
.. method:: done()
Return ``True`` if the Future is *done*.
A Future is *done* if it was *cancelled* or if it has a result
or an exception set with :meth:`set_result` or
:meth:`set_exception` calls.
.. method:: cancelled()
Return ``True`` if the Future was *cancelled*.
The method is usually used to check if a Future is not
*cancelled* before setting a result or an exception for it::
if not fut.cancelled():
fut.set_result(42)
.. method:: add_done_callback(callback, *, context=None)
Add a callback to be run when the Future is *done*.
The *callback* is called with the Future object as its only
argument.
If the Future is already *done* when this method is called,
the callback is scheduled with :meth:`loop.call_soon`.
An optional keyword-only *context* argument allows specifying a
custom :class:`contextvars.Context` for the *callback* to run in.
The current context is used when no *context* is provided.
:func:`functools.partial` can be used to pass parameters
to the callback, e.g.::
# Call 'print("Future:", fut)' when "fut" is done.
fut.add_done_callback(
functools.partial(print, "Future:"))
.. versionchanged:: 3.7
The *context* keyword-only parameter was added.
See :pep:`567` for more details.
.. method:: remove_done_callback(callback)
Remove *callback* from the callbacks list.
Returns the number of callbacks removed, which is typically 1,
unless a callback was added more than once.
.. method:: cancel()
Cancel the Future and schedule callbacks.
If the Future is already *done* or *cancelled*, return ``False``.
Otherwise, change the Future's state to *cancelled*,
schedule the callbacks, and return ``True``.
.. method:: exception()
Return the exception that was set on this Future.
The exception (or ``None`` if no exception was set) is
returned only if the Future is *done*.
If the Future has been *cancelled*, this method raises a
:exc:`CancelledError` exception.
If the Future isn't *done* yet, this method raises an
:exc:`InvalidStateError` exception.
.. method:: get_loop()
Return the event loop the Future object is bound to.
.. versionadded:: 3.7
.. _asyncio_example_future:
This example creates a Future object, creates and schedules an
asynchronous Task to set result for the Future, and waits until
the Future has a result::
async def set_after(fut, delay, value):
# Sleep for *delay* seconds.
await asyncio.sleep(delay)
# Set *value* as a result of *fut* Future.
fut.set_result(value)
async def main():
# Get the current event loop.
loop = asyncio.get_running_loop()
# Create a new Future object.
fut = loop.create_future()
# Run "set_after()" coroutine in a parallel Task.
# We are using the low-level "loop.create_task()" API here because
# we already have a reference to the event loop at hand.
# Otherwise we could have just used "asyncio.create_task()".
loop.create_task(
set_after(fut, 1, '... world'))
print('hello ...')
# Wait until *fut* has a result (1 second) and print it.
print(await fut)
asyncio.run(main())
.. important::
The Future object was designed to mimic
:class:`concurrent.futures.Future`. Key differences include:
- unlike asyncio Futures, :class:`concurrent.futures.Future`
instances cannot be awaited.
- :meth:`asyncio.Future.result` and :meth:`asyncio.Future.exception`
do not accept the *timeout* argument.
- :meth:`asyncio.Future.result` and :meth:`asyncio.Future.exception`
raise an :exc:`InvalidStateError` exception when the Future is not
*done*.
- Callbacks registered with :meth:`asyncio.Future.add_done_callback`
are not called immediately. They are scheduled with
:meth:`loop.call_soon` instead.
- asyncio Future is not compatible with the
:func:`concurrent.futures.wait` and
:func:`concurrent.futures.as_completed` functions.

510
web/python-docs/_sources/library/asyncio-llapi-index.rst.txt Normal file
View File

@@ -0,0 +1,510 @@
.. currentmodule:: asyncio
===================
Low-level API Index
===================
This page lists all low-level asyncio APIs.
Obtaining the Event Loop
========================
.. list-table::
:widths: 50 50
:class: full-width-table
* - :func:`asyncio.get_running_loop`
- The **preferred** function to get the running event loop.
* - :func:`asyncio.get_event_loop`
- Get an event loop instance (current or via the policy).
* - :func:`asyncio.set_event_loop`
- Set the event loop as current via the current policy.
* - :func:`asyncio.new_event_loop`
- Create a new event loop.
.. rubric:: Examples
* :ref:`Using asyncio.get_running_loop() <asyncio_example_future>`.
Event Loop Methods
==================
See also the main documentation section about the
:ref:`event loop methods <asyncio-event-loop>`.
.. rubric:: Lifecycle
.. list-table::
:widths: 50 50
:class: full-width-table
* - :meth:`loop.run_until_complete`
- Run a Future/Task/awaitable until complete.
* - :meth:`loop.run_forever`
- Run the event loop forever.
* - :meth:`loop.stop`
- Stop the event loop.
* - :meth:`loop.close`
- Close the event loop.
* - :meth:`loop.is_running()`
- Return ``True`` if the event loop is running.
* - :meth:`loop.is_closed()`
- Return ``True`` if the event loop is closed.
* - ``await`` :meth:`loop.shutdown_asyncgens`
- Close asynchronous generators.
.. rubric:: Debugging
.. list-table::
:widths: 50 50
:class: full-width-table
* - :meth:`loop.set_debug`
- Enable or disable the debug mode.
* - :meth:`loop.get_debug`
- Get the current debug mode.
.. rubric:: Scheduling Callbacks
.. list-table::
:widths: 50 50
:class: full-width-table
* - :meth:`loop.call_soon`
- Invoke a callback soon.
* - :meth:`loop.call_soon_threadsafe`
- A thread-safe variant of :meth:`loop.call_soon`.
* - :meth:`loop.call_later`
- Invoke a callback *after* the given time.
* - :meth:`loop.call_at`
- Invoke a callback *at* the given time.
.. rubric:: Thread/Process Pool
.. list-table::
:widths: 50 50
:class: full-width-table
* - ``await`` :meth:`loop.run_in_executor`
- Run a CPU-bound or other blocking function in
a :mod:`concurrent.futures` executor.
* - :meth:`loop.set_default_executor`
- Set the default executor for :meth:`loop.run_in_executor`.
.. rubric:: Tasks and Futures
.. list-table::
:widths: 50 50
:class: full-width-table
* - :meth:`loop.create_future`
- Create a :class:`Future` object.
* - :meth:`loop.create_task`
- Schedule coroutine as a :class:`Task`.
* - :meth:`loop.set_task_factory`
- Set a factory used by :meth:`loop.create_task` to
create :class:`Tasks <Task>`.
* - :meth:`loop.get_task_factory`
- Get the factory :meth:`loop.create_task` uses
to create :class:`Tasks <Task>`.
.. rubric:: DNS
.. list-table::
:widths: 50 50
:class: full-width-table
* - ``await`` :meth:`loop.getaddrinfo`
- Asynchronous version of :meth:`socket.getaddrinfo`.
* - ``await`` :meth:`loop.getnameinfo`
- Asynchronous version of :meth:`socket.getnameinfo`.
.. rubric:: Networking and IPC
.. list-table::
:widths: 50 50
:class: full-width-table
* - ``await`` :meth:`loop.create_connection`
- Open a TCP connection.
* - ``await`` :meth:`loop.create_server`
- Create a TCP server.
* - ``await`` :meth:`loop.create_unix_connection`
- Open a Unix socket connection.
* - ``await`` :meth:`loop.create_unix_server`
- Create a Unix socket server.
* - ``await`` :meth:`loop.connect_accepted_socket`
- Wrap a :class:`~socket.socket` into a ``(transport, protocol)``
pair.
* - ``await`` :meth:`loop.create_datagram_endpoint`
- Open a datagram (UDP) connection.
* - ``await`` :meth:`loop.sendfile`
- Send a file over a transport.
* - ``await`` :meth:`loop.start_tls`
- Upgrade an existing connection to TLS.
* - ``await`` :meth:`loop.connect_read_pipe`
- Wrap a read end of a pipe into a ``(transport, protocol)`` pair.
* - ``await`` :meth:`loop.connect_write_pipe`
- Wrap a write end of a pipe into a ``(transport, protocol)`` pair.
.. rubric:: Sockets
.. list-table::
:widths: 50 50
:class: full-width-table
* - ``await`` :meth:`loop.sock_recv`
- Receive data from the :class:`~socket.socket`.
* - ``await`` :meth:`loop.sock_recv_into`
- Receive data from the :class:`~socket.socket` into a buffer.
* - ``await`` :meth:`loop.sock_sendall`
- Send data to the :class:`~socket.socket`.
* - ``await`` :meth:`loop.sock_connect`
- Connect the :class:`~socket.socket`.
* - ``await`` :meth:`loop.sock_accept`
- Accept a :class:`~socket.socket` connection.
* - ``await`` :meth:`loop.sock_sendfile`
- Send a file over the :class:`~socket.socket`.
* - :meth:`loop.add_reader`
- Start watching a file descriptor for read availability.
* - :meth:`loop.remove_reader`
- Stop watching a file descriptor for read availability.
* - :meth:`loop.add_writer`
- Start watching a file descriptor for write availability.
* - :meth:`loop.remove_writer`
- Stop watching a file descriptor for write availability.
.. rubric:: Unix Signals
.. list-table::
:widths: 50 50
:class: full-width-table
* - :meth:`loop.add_signal_handler`
- Add a handler for a :mod:`signal`.
* - :meth:`loop.remove_signal_handler`
- Remove a handler for a :mod:`signal`.
.. rubric:: Subprocesses
.. list-table::
:widths: 50 50
:class: full-width-table
* - :meth:`loop.subprocess_exec`
- Spawn a subprocess.
* - :meth:`loop.subprocess_shell`
- Spawn a subprocess from a shell command.
.. rubric:: Error Handling
.. list-table::
:widths: 50 50
:class: full-width-table
* - :meth:`loop.call_exception_handler`
- Call the exception handler.
* - :meth:`loop.set_exception_handler`
- Set a new exception handler.
* - :meth:`loop.get_exception_handler`
- Get the current exception handler.
* - :meth:`loop.default_exception_handler`
- The default exception handler implementation.
.. rubric:: Examples
* :ref:`Using asyncio.get_event_loop() and loop.run_forever()
<asyncio_example_lowlevel_helloworld>`.
* :ref:`Using loop.call_later() <asyncio_example_call_later>`.
* Using ``loop.create_connection()`` to implement
:ref:`an echo-client <asyncio_example_tcp_echo_client_protocol>`.
* Using ``loop.create_connection()`` to
:ref:`connect a socket <asyncio_example_create_connection>`.
* :ref:`Using add_reader() to watch an FD for read events
<asyncio_example_watch_fd>`.
* :ref:`Using loop.add_signal_handler() <asyncio_example_unix_signals>`.
* :ref:`Using loop.subprocess_exec() <asyncio_example_subprocess_proto>`.
Transports
==========
All transports implement the following methods:
.. list-table::
:widths: 50 50
:class: full-width-table
* - :meth:`transport.close() <BaseTransport.close>`
- Close the transport.
* - :meth:`transport.is_closing() <BaseTransport.is_closing>`
- Return ``True`` if the transport is closing or is closed.
* - :meth:`transport.get_extra_info() <BaseTransport.get_extra_info>`
- Request for information about the transport.
* - :meth:`transport.set_protocol() <BaseTransport.set_protocol>`
- Set a new protocol.
* - :meth:`transport.get_protocol() <BaseTransport.get_protocol>`
- Return the current protocol.
Transports that can receive data (TCP and Unix connections,
pipes, etc). Returned from methods like
:meth:`loop.create_connection`, :meth:`loop.create_unix_connection`,
:meth:`loop.connect_read_pipe`, etc:
.. rubric:: Read Transports
.. list-table::
:widths: 50 50
:class: full-width-table
* - :meth:`transport.is_reading() <ReadTransport.is_reading>`
- Return ``True`` if the transport is receiving.
* - :meth:`transport.pause_reading() <ReadTransport.pause_reading>`
- Pause receiving.
* - :meth:`transport.resume_reading() <ReadTransport.resume_reading>`
- Resume receiving.
Transports that can Send data (TCP and Unix connections,
pipes, etc). Returned from methods like
:meth:`loop.create_connection`, :meth:`loop.create_unix_connection`,
:meth:`loop.connect_write_pipe`, etc:
.. rubric:: Write Transports
.. list-table::
:widths: 50 50
:class: full-width-table
* - :meth:`transport.write() <WriteTransport.write>`
- Write data to the transport.
* - :meth:`transport.writelines() <WriteTransport.writelines>`
- Write buffers to the transport.
* - :meth:`transport.can_write_eof() <WriteTransport.can_write_eof>`
- Return :const:`True` if the transport supports sending EOF.
* - :meth:`transport.write_eof() <WriteTransport.write_eof>`
- Close and send EOF after flushing buffered data.
* - :meth:`transport.abort() <WriteTransport.abort>`
- Close the transport immediately.
* - :meth:`transport.get_write_buffer_size()
<WriteTransport.get_write_buffer_size>`
- Return high and low water marks for write flow control.
* - :meth:`transport.set_write_buffer_limits()
<WriteTransport.set_write_buffer_limits>`
- Set new high and low water marks for write flow control.
Transports returned by :meth:`loop.create_datagram_endpoint`:
.. rubric:: Datagram Transports
.. list-table::
:widths: 50 50
:class: full-width-table
* - :meth:`transport.sendto() <DatagramTransport.sendto>`
- Send data to the remote peer.
* - :meth:`transport.abort() <DatagramTransport.abort>`
- Close the transport immediately.
Low-level transport abstraction over subprocesses.
Returned by :meth:`loop.subprocess_exec` and
:meth:`loop.subprocess_shell`:
.. rubric:: Subprocess Transports
.. list-table::
:widths: 50 50
:class: full-width-table
* - :meth:`transport.get_pid() <SubprocessTransport.get_pid>`
- Return the subprocess process id.
* - :meth:`transport.get_pipe_transport()
<SubprocessTransport.get_pipe_transport>`
- Return the transport for the requested communication pipe
(*stdin*, *stdout*, or *stderr*).
* - :meth:`transport.get_returncode() <SubprocessTransport.get_returncode>`
- Return the subprocess return code.
* - :meth:`transport.kill() <SubprocessTransport.kill>`
- Kill the subprocess.
* - :meth:`transport.send_signal() <SubprocessTransport.send_signal>`
- Send a signal to the subprocess.
* - :meth:`transport.terminate() <SubprocessTransport.terminate>`
- Stop the subprocess.
* - :meth:`transport.close() <SubprocessTransport.close>`
- Kill the subprocess and close all pipes.
Protocols
=========
Protocol classes can implement the following **callback methods**:
.. list-table::
:widths: 50 50
:class: full-width-table
* - ``callback`` :meth:`connection_made() <BaseProtocol.connection_made>`
- Called when a connection is made.
* - ``callback`` :meth:`connection_lost() <BaseProtocol.connection_lost>`
- Called when the connection is lost or closed.
* - ``callback`` :meth:`pause_writing() <BaseProtocol.pause_writing>`
- Called when the transport's buffer goes over the high water mark.
* - ``callback`` :meth:`resume_writing() <BaseProtocol.resume_writing>`
- Called when the transport's buffer drains below the low water mark.
.. rubric:: Streaming Protocols (TCP, Unix Sockets, Pipes)
.. list-table::
:widths: 50 50
:class: full-width-table
* - ``callback`` :meth:`data_received() <Protocol.data_received>`
- Called when some data is received.
* - ``callback`` :meth:`eof_received() <Protocol.eof_received>`
- Called when an EOF is received.
.. rubric:: Buffered Streaming Protocols
.. list-table::
:widths: 50 50
:class: full-width-table
* - ``callback`` :meth:`get_buffer() <BufferedProtocol.get_buffer>`
- Called to allocate a new receive buffer.
* - ``callback`` :meth:`buffer_updated() <BufferedProtocol.buffer_updated>`
- Called when the buffer was updated with the received data.
* - ``callback`` :meth:`eof_received() <BufferedProtocol.eof_received>`
- Called when an EOF is received.
.. rubric:: Datagram Protocols
.. list-table::
:widths: 50 50
:class: full-width-table
* - ``callback`` :meth:`datagram_received()
<DatagramProtocol.datagram_received>`
- Called when a datagram is received.
* - ``callback`` :meth:`error_received() <DatagramProtocol.error_received>`
- Called when a previous send or receive operation raises an
:class:`OSError`.
.. rubric:: Subprocess Protocols
.. list-table::
:widths: 50 50
:class: full-width-table
* - ``callback`` :meth:`pipe_data_received()
<SubprocessProtocol.pipe_data_received>`
- Called when the child process writes data into its
*stdout* or *stderr* pipe.
* - ``callback`` :meth:`pipe_connection_lost()
<SubprocessProtocol.pipe_connection_lost>`
- Called when one of the pipes communicating with
the child process is closed.
* - ``callback`` :meth:`process_exited()
<SubprocessProtocol.process_exited>`
- Called when the child process has exited.
Event Loop Policies
===================
Policies is a low-level mechanism to alter the behavior of
functions like :func:`asyncio.get_event_loop`. See also
the main :ref:`policies section <asyncio-policies>` for more
details.
.. rubric:: Accessing Policies
.. list-table::
:widths: 50 50
:class: full-width-table
* - :meth:`asyncio.get_event_loop_policy`
- Return the current process-wide policy.
* - :meth:`asyncio.set_event_loop_policy`
- Set a new process-wide policy.
* - :class:`AbstractEventLoopPolicy`
- Base class for policy objects.

105
web/python-docs/_sources/library/asyncio-platforms.rst.txt Normal file
View File

@@ -0,0 +1,105 @@
.. currentmodule:: asyncio
.. _asyncio-platform-support:
================
Platform Support
================
The :mod:`asyncio` module is designed to be portable,
but some platforms have subtle differences and limitations
due to the platforms' underlying architecture and capabilities.
All Platforms
=============
* :meth:`loop.add_reader` and :meth:`loop.add_writer`
cannot be used to monitor file I/O.
Windows
=======
**Source code:** :source:`Lib/asyncio/proactor_events.py`,
:source:`Lib/asyncio/windows_events.py`,
:source:`Lib/asyncio/windows_utils.py`
--------------------------------------
.. versionchanged:: 3.8
On Windows, :class:`ProactorEventLoop` is now the default event loop.
All event loops on Windows do not support the following methods:
* :meth:`loop.create_unix_connection` and
:meth:`loop.create_unix_server` are not supported.
The :data:`socket.AF_UNIX` socket family is specific to Unix.
* :meth:`loop.add_signal_handler` and
:meth:`loop.remove_signal_handler` are not supported.
:class:`SelectorEventLoop` has the following limitations:
* :class:`~selectors.SelectSelector` is used to wait on socket events:
it supports sockets and is limited to 512 sockets.
* :meth:`loop.add_reader` and :meth:`loop.add_writer` only accept
socket handles (e.g. pipe file descriptors are not supported).
* Pipes are not supported, so the :meth:`loop.connect_read_pipe`
and :meth:`loop.connect_write_pipe` methods are not implemented.
* :ref:`Subprocesses <asyncio-subprocess>` are not supported, i.e.
:meth:`loop.subprocess_exec` and :meth:`loop.subprocess_shell`
methods are not implemented.
:class:`ProactorEventLoop` has the following limitations:
* The :meth:`loop.add_reader` and :meth:`loop.add_writer`
methods are not supported.
The resolution of the monotonic clock on Windows is usually around 15.6
msec. The best resolution is 0.5 msec. The resolution depends on the
hardware (availability of `HPET
<https://en.wikipedia.org/wiki/High_Precision_Event_Timer>`_) and on the
Windows configuration.
.. _asyncio-windows-subprocess:
Subprocess Support on Windows
-----------------------------
On Windows, the default event loop :class:`ProactorEventLoop` supports
subprocesses, whereas :class:`SelectorEventLoop` does not.
The :meth:`policy.set_child_watcher()
<AbstractEventLoopPolicy.set_child_watcher>` function is also
not supported, as :class:`ProactorEventLoop` has a different mechanism
to watch child processes.
macOS
=====
Modern macOS versions are fully supported.
.. rubric:: macOS <= 10.8
On macOS 10.6, 10.7 and 10.8, the default event loop
uses :class:`selectors.KqueueSelector`, which does not support
character devices on these versions. The :class:`SelectorEventLoop`
can be manually configured to use :class:`~selectors.SelectSelector`
or :class:`~selectors.PollSelector` to support character devices on
these older versions of macOS. Example::
import asyncio
import selectors
selector = selectors.SelectSelector()
loop = asyncio.SelectorEventLoop(selector)
asyncio.set_event_loop(loop)

279
web/python-docs/_sources/library/asyncio-policy.rst.txt Normal file
View File

@@ -0,0 +1,279 @@
.. currentmodule:: asyncio
.. _asyncio-policies:
========
Policies
========
An event loop policy is a global per-process object that controls
the management of the event loop. Each event loop has a default
policy, which can be changed and customized using the policy API.
A policy defines the notion of *context* and manages a
separate event loop per context. The default policy
defines *context* to be the current thread.
By using a custom event loop policy, the behavior of
:func:`get_event_loop`, :func:`set_event_loop`, and
:func:`new_event_loop` functions can be customized.
Policy objects should implement the APIs defined
in the :class:`AbstractEventLoopPolicy` abstract base class.
Getting and Setting the Policy
==============================
The following functions can be used to get and set the policy
for the current process:
.. function:: get_event_loop_policy()
Return the current process-wide policy.
.. function:: set_event_loop_policy(policy)
Set the current process-wide policy to *policy*.
If *policy* is set to ``None``, the default policy is restored.
Policy Objects
==============
The abstract event loop policy base class is defined as follows:
.. class:: AbstractEventLoopPolicy
An abstract base class for asyncio policies.
.. method:: get_event_loop()
Get the event loop for the current context.
Return an event loop object implementing the
:class:`AbstractEventLoop` interface.
This method should never return ``None``.
.. versionchanged:: 3.6
.. method:: set_event_loop(loop)
Set the event loop for the current context to *loop*.
.. method:: new_event_loop()
Create and return a new event loop object.
This method should never return ``None``.
.. method:: get_child_watcher()
Get a child process watcher object.
Return a watcher object implementing the
:class:`AbstractChildWatcher` interface.
This function is Unix specific.
.. method:: set_child_watcher(watcher)
Set the current child process watcher to *watcher*.
This function is Unix specific.
asyncio ships with the following built-in policies:
.. class:: DefaultEventLoopPolicy
The default asyncio policy. Uses :class:`SelectorEventLoop`
on Unix and :class:`ProactorEventLoop` on Windows.
There is no need to install the default policy manually. asyncio
is configured to use the default policy automatically.
.. versionchanged:: 3.8
On Windows, :class:`ProactorEventLoop` is now used by default.
.. class:: WindowsSelectorEventLoopPolicy
An alternative event loop policy that uses the
:class:`SelectorEventLoop` event loop implementation.
.. availability:: Windows.
.. class:: WindowsProactorEventLoopPolicy
An alternative event loop policy that uses the
:class:`ProactorEventLoop` event loop implementation.
.. availability:: Windows.
.. _asyncio-watchers:
Process Watchers
================
A process watcher allows customization of how an event loop monitors
child processes on Unix. Specifically, the event loop needs to know
when a child process has exited.
In asyncio, child processes are created with
:func:`create_subprocess_exec` and :meth:`loop.subprocess_exec`
functions.
asyncio defines the :class:`AbstractChildWatcher` abstract base class, which child
watchers should implement, and has four different implementations:
:class:`ThreadedChildWatcher` (configured to be used by default),
:class:`MultiLoopChildWatcher`, :class:`SafeChildWatcher`, and
:class:`FastChildWatcher`.
See also the :ref:`Subprocess and Threads <asyncio-subprocess-threads>`
section.
The following two functions can be used to customize the child process watcher
implementation used by the asyncio event loop:
.. function:: get_child_watcher()
Return the current child watcher for the current policy.
.. function:: set_child_watcher(watcher)
Set the current child watcher to *watcher* for the current
policy. *watcher* must implement methods defined in the
:class:`AbstractChildWatcher` base class.
.. note::
Third-party event loops implementations might not support
custom child watchers. For such event loops, using
:func:`set_child_watcher` might be prohibited or have no effect.
.. class:: AbstractChildWatcher
.. method:: add_child_handler(pid, callback, *args)
Register a new child handler.
Arrange for ``callback(pid, returncode, *args)`` to be called
when a process with PID equal to *pid* terminates. Specifying
another callback for the same process replaces the previous
handler.
The *callback* callable must be thread-safe.
.. method:: remove_child_handler(pid)
Removes the handler for process with PID equal to *pid*.
The function returns ``True`` if the handler was successfully
removed, ``False`` if there was nothing to remove.
.. method:: attach_loop(loop)
Attach the watcher to an event loop.
If the watcher was previously attached to an event loop, then
it is first detached before attaching to the new loop.
Note: loop may be ``None``.
.. method:: is_active()
Return ``True`` if the watcher is ready to use.
Spawning a subprocess with *inactive* current child watcher raises
:exc:`RuntimeError`.
.. versionadded:: 3.8
.. method:: close()
Close the watcher.
This method has to be called to ensure that underlying
resources are cleaned-up.
.. class:: ThreadedChildWatcher
This implementation starts a new waiting thread for every subprocess spawn.
It works reliably even when the asyncio event loop is run in a non-main OS thread.
There is no noticeable overhead when handling a big number of children (*O(1)* each
time a child terminates), but starting a thread per process requires extra memory.
This watcher is used by default.
.. versionadded:: 3.8
.. class:: MultiLoopChildWatcher
This implementation registers a :py:data:`SIGCHLD` signal handler on
instantiation. That can break third-party code that installs a custom handler for
:py:data:`SIGCHLD` signal.
The watcher avoids disrupting other code spawning processes
by polling every process explicitly on a :py:data:`SIGCHLD` signal.
There is no limitation for running subprocesses from different threads once the
watcher is installed.
The solution is safe but it has a significant overhead when
handling a big number of processes (*O(n)* each time a
:py:data:`SIGCHLD` is received).
.. versionadded:: 3.8
.. class:: SafeChildWatcher
This implementation uses active event loop from the main thread to handle
:py:data:`SIGCHLD` signal. If the main thread has no running event loop another
thread cannot spawn a subprocess (:exc:`RuntimeError` is raised).
The watcher avoids disrupting other code spawning processes
by polling every process explicitly on a :py:data:`SIGCHLD` signal.
This solution is as safe as :class:`MultiLoopChildWatcher` and has the same *O(N)*
complexity but requires a running event loop in the main thread to work.
.. class:: FastChildWatcher
This implementation reaps every terminated processes by calling
``os.waitpid(-1)`` directly, possibly breaking other code spawning
processes and waiting for their termination.
There is no noticeable overhead when handling a big number of
children (*O(1)* each time a child terminates).
This solution requires a running event loop in the main thread to work, as
:class:`SafeChildWatcher`.
Custom Policies
===============
To implement a new event loop policy, it is recommended to subclass
:class:`DefaultEventLoopPolicy` and override the methods for which
custom behavior is wanted, e.g.::
class MyEventLoopPolicy(asyncio.DefaultEventLoopPolicy):
def get_event_loop(self):
"""Get the event loop.
This may be None or an instance of EventLoop.
"""
loop = super().get_event_loop()
# Do something with loop ...
return loop
asyncio.set_event_loop_policy(MyEventLoopPolicy())

1046
web/python-docs/_sources/library/asyncio-protocol.rst.txt Normal file
View File

File diff suppressed because it is too large Load Diff

208
web/python-docs/_sources/library/asyncio-queue.rst.txt Normal file
View File

@@ -0,0 +1,208 @@
.. currentmodule:: asyncio
.. _asyncio-queues:
======
Queues
======
**Source code:** :source:`Lib/asyncio/queues.py`
------------------------------------------------
asyncio queues are designed to be similar to classes of the
:mod:`queue` module. Although asyncio queues are not thread-safe,
they are designed to be used specifically in async/await code.
Note that methods of asyncio queues don't have a *timeout* parameter;
use :func:`asyncio.wait_for` function to do queue operations with a
timeout.
See also the `Examples`_ section below.
Queue
=====
.. class:: Queue(maxsize=0, \*, loop=None)
A first in, first out (FIFO) queue.
If *maxsize* is less than or equal to zero, the queue size is
infinite. If it is an integer greater than ``0``, then
``await put()`` blocks when the queue reaches *maxsize*
until an item is removed by :meth:`get`.
Unlike the standard library threading :mod:`queue`, the size of
the queue is always known and can be returned by calling the
:meth:`qsize` method.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
This class is :ref:`not thread safe <asyncio-multithreading>`.
.. attribute:: maxsize
Number of items allowed in the queue.
.. method:: empty()
Return ``True`` if the queue is empty, ``False`` otherwise.
.. method:: full()
Return ``True`` if there are :attr:`maxsize` items in the queue.
If the queue was initialized with ``maxsize=0`` (the default),
then :meth:`full()` never returns ``True``.
.. coroutinemethod:: get()
Remove and return an item from the queue. If queue is empty,
wait until an item is available.
.. method:: get_nowait()
Return an item if one is immediately available, else raise
:exc:`QueueEmpty`.
.. coroutinemethod:: join()
Block until all items in the queue have been received and processed.
The count of unfinished tasks goes up whenever an item is added
to the queue. The count goes down whenever a consumer coroutine calls
:meth:`task_done` to indicate that the item was retrieved and all
work on it is complete. When the count of unfinished tasks drops
to zero, :meth:`join` unblocks.
.. coroutinemethod:: put(item)
Put an item into the queue. If the queue is full, wait until a
free slot is available before adding the item.
.. method:: put_nowait(item)
Put an item into the queue without blocking.
If no free slot is immediately available, raise :exc:`QueueFull`.
.. method:: qsize()
Return the number of items in the queue.
.. method:: task_done()
Indicate that a formerly enqueued task is complete.
Used by queue consumers. For each :meth:`~Queue.get` used to
fetch a task, a subsequent call to :meth:`task_done` tells the
queue that the processing on the task is complete.
If a :meth:`join` is currently blocking, it will resume when all
items have been processed (meaning that a :meth:`task_done`
call was received for every item that had been :meth:`~Queue.put`
into the queue).
Raises :exc:`ValueError` if called more times than there were
items placed in the queue.
Priority Queue
==============
.. class:: PriorityQueue
A variant of :class:`Queue`; retrieves entries in priority order
(lowest first).
Entries are typically tuples of the form
``(priority_number, data)``.
LIFO Queue
==========
.. class:: LifoQueue
A variant of :class:`Queue` that retrieves most recently added
entries first (last in, first out).
Exceptions
==========
.. exception:: QueueEmpty
This exception is raised when the :meth:`~Queue.get_nowait` method
is called on an empty queue.
.. exception:: QueueFull
Exception raised when the :meth:`~Queue.put_nowait` method is called
on a queue that has reached its *maxsize*.
Examples
========
.. _asyncio_example_queue_dist:
Queues can be used to distribute workload between several
concurrent tasks::
import asyncio
import random
import time
async def worker(name, queue):
while True:
# Get a "work item" out of the queue.
sleep_for = await queue.get()
# Sleep for the "sleep_for" seconds.
await asyncio.sleep(sleep_for)
# Notify the queue that the "work item" has been processed.
queue.task_done()
print(f'{name} has slept for {sleep_for:.2f} seconds')
async def main():
# Create a queue that we will use to store our "workload".
queue = asyncio.Queue()
# Generate random timings and put them into the queue.
total_sleep_time = 0
for _ in range(20):
sleep_for = random.uniform(0.05, 1.0)
total_sleep_time += sleep_for
queue.put_nowait(sleep_for)
# Create three worker tasks to process the queue concurrently.
tasks = []
for i in range(3):
task = asyncio.create_task(worker(f'worker-{i}', queue))
tasks.append(task)
# Wait until the queue is fully processed.
started_at = time.monotonic()
await queue.join()
total_slept_for = time.monotonic() - started_at
# Cancel our worker tasks.
for task in tasks:
task.cancel()
# Wait until all worker tasks are cancelled.
await asyncio.gather(*tasks, return_exceptions=True)
print('====')
print(f'3 workers slept in parallel for {total_slept_for:.2f} seconds')
print(f'total expected sleep time: {total_sleep_time:.2f} seconds')
asyncio.run(main())

486
web/python-docs/_sources/library/asyncio-stream.rst.txt Normal file
View File

@@ -0,0 +1,486 @@
.. currentmodule:: asyncio
.. _asyncio-streams:
=======
Streams
=======
**Source code:** :source:`Lib/asyncio/streams.py`
-------------------------------------------------
Streams are high-level async/await-ready primitives to work with
network connections. Streams allow sending and receiving data without
using callbacks or low-level protocols and transports.
.. _asyncio_example_stream:
Here is an example of a TCP echo client written using asyncio
streams::
import asyncio
async def tcp_echo_client(message):
reader, writer = await asyncio.open_connection(
'127.0.0.1', 8888)
print(f'Send: {message!r}')
writer.write(message.encode())
await writer.drain()
data = await reader.read(100)
print(f'Received: {data.decode()!r}')
print('Close the connection')
writer.close()
await writer.wait_closed()
asyncio.run(tcp_echo_client('Hello World!'))
See also the `Examples`_ section below.
.. rubric:: Stream Functions
The following top-level asyncio functions can be used to create
and work with streams:
.. coroutinefunction:: open_connection(host=None, port=None, *, \
loop=None, limit=None, ssl=None, family=0, \
proto=0, flags=0, sock=None, local_addr=None, \
server_hostname=None, ssl_handshake_timeout=None)
Establish a network connection and return a pair of
``(reader, writer)`` objects.
The returned *reader* and *writer* objects are instances of
:class:`StreamReader` and :class:`StreamWriter` classes.
The *loop* argument is optional and can always be determined
automatically when this function is awaited from a coroutine.
*limit* determines the buffer size limit used by the
returned :class:`StreamReader` instance. By default the *limit*
is set to 64 KiB.
The rest of the arguments are passed directly to
:meth:`loop.create_connection`.
.. versionadded:: 3.7
The *ssl_handshake_timeout* parameter.
.. coroutinefunction:: start_server(client_connected_cb, host=None, \
port=None, *, loop=None, limit=None, \
family=socket.AF_UNSPEC, \
flags=socket.AI_PASSIVE, sock=None, \
backlog=100, ssl=None, reuse_address=None, \
reuse_port=None, ssl_handshake_timeout=None, \
start_serving=True)
Start a socket server.
The *client_connected_cb* callback is called whenever a new client
connection is established. It receives a ``(reader, writer)`` pair
as two arguments, instances of the :class:`StreamReader` and
:class:`StreamWriter` classes.
*client_connected_cb* can be a plain callable or a
:ref:`coroutine function <coroutine>`; if it is a coroutine function,
it will be automatically scheduled as a :class:`Task`.
The *loop* argument is optional and can always be determined
automatically when this method is awaited from a coroutine.
*limit* determines the buffer size limit used by the
returned :class:`StreamReader` instance. By default the *limit*
is set to 64 KiB.
The rest of the arguments are passed directly to
:meth:`loop.create_server`.
.. versionadded:: 3.7
The *ssl_handshake_timeout* and *start_serving* parameters.
.. rubric:: Unix Sockets
.. coroutinefunction:: open_unix_connection(path=None, *, loop=None, \
limit=None, ssl=None, sock=None, \
server_hostname=None, ssl_handshake_timeout=None)
Establish a Unix socket connection and return a pair of
``(reader, writer)``.
Similar to :func:`open_connection` but operates on Unix sockets.
See also the documentation of :meth:`loop.create_unix_connection`.
.. availability:: Unix.
.. versionadded:: 3.7
The *ssl_handshake_timeout* parameter.
.. versionchanged:: 3.7
The *path* parameter can now be a :term:`path-like object`
.. coroutinefunction:: start_unix_server(client_connected_cb, path=None, \
*, loop=None, limit=None, sock=None, \
backlog=100, ssl=None, ssl_handshake_timeout=None, \
start_serving=True)
Start a Unix socket server.
Similar to :func:`start_server` but works with Unix sockets.
See also the documentation of :meth:`loop.create_unix_server`.
.. availability:: Unix.
.. versionadded:: 3.7
The *ssl_handshake_timeout* and *start_serving* parameters.
.. versionchanged:: 3.7
The *path* parameter can now be a :term:`path-like object`.
StreamReader
============
.. class:: StreamReader
Represents a reader object that provides APIs to read data
from the IO stream.
It is not recommended to instantiate *StreamReader* objects
directly; use :func:`open_connection` and :func:`start_server`
instead.
.. coroutinemethod:: read(n=-1)
Read up to *n* bytes. If *n* is not provided, or set to ``-1``,
read until EOF and return all read bytes.
If EOF was received and the internal buffer is empty,
return an empty ``bytes`` object.
.. coroutinemethod:: readline()
Read one line, where "line" is a sequence of bytes
ending with ``\n``.
If EOF is received and ``\n`` was not found, the method
returns partially read data.
If EOF is received and the internal buffer is empty,
return an empty ``bytes`` object.
.. coroutinemethod:: readexactly(n)
Read exactly *n* bytes.
Raise an :exc:`IncompleteReadError` if EOF is reached before *n*
can be read. Use the :attr:`IncompleteReadError.partial`
attribute to get the partially read data.
.. coroutinemethod:: readuntil(separator=b'\\n')
Read data from the stream until *separator* is found.
On success, the data and separator will be removed from the
internal buffer (consumed). Returned data will include the
separator at the end.
If the amount of data read exceeds the configured stream limit, a
:exc:`LimitOverrunError` exception is raised, and the data
is left in the internal buffer and can be read again.
If EOF is reached before the complete separator is found,
an :exc:`IncompleteReadError` exception is raised, and the internal
buffer is reset. The :attr:`IncompleteReadError.partial` attribute
may contain a portion of the separator.
.. versionadded:: 3.5.2
.. method:: at_eof()
Return ``True`` if the buffer is empty and :meth:`feed_eof`
was called.
StreamWriter
============
.. class:: StreamWriter
Represents a writer object that provides APIs to write data
to the IO stream.
It is not recommended to instantiate *StreamWriter* objects
directly; use :func:`open_connection` and :func:`start_server`
instead.
.. method:: write(data)
The method attempts to write the *data* to the underlying socket immediately.
If that fails, the data is queued in an internal write buffer until it can be
sent.
The method should be used along with the ``drain()`` method::
stream.write(data)
await stream.drain()
.. method:: writelines(data)
The method writes a list (or any iterable) of bytes to the underlying socket
immediately.
If that fails, the data is queued in an internal write buffer until it can be
sent.
The method should be used along with the ``drain()`` method::
stream.writelines(lines)
await stream.drain()
.. method:: close()
The method closes the stream and the underlying socket.
The method should be used along with the ``wait_closed()`` method::
stream.close()
await stream.wait_closed()
.. method:: can_write_eof()
Return ``True`` if the underlying transport supports
the :meth:`write_eof` method, ``False`` otherwise.
.. method:: write_eof()
Close the write end of the stream after the buffered write
data is flushed.
.. attribute:: transport
Return the underlying asyncio transport.
.. method:: get_extra_info(name, default=None)
Access optional transport information; see
:meth:`BaseTransport.get_extra_info` for details.
.. coroutinemethod:: drain()
Wait until it is appropriate to resume writing to the stream.
Example::
writer.write(data)
await writer.drain()
This is a flow control method that interacts with the underlying
IO write buffer. When the size of the buffer reaches
the high watermark, *drain()* blocks until the size of the
buffer is drained down to the low watermark and writing can
be resumed. When there is nothing to wait for, the :meth:`drain`
returns immediately.
.. method:: is_closing()
Return ``True`` if the stream is closed or in the process of
being closed.
.. versionadded:: 3.7
.. coroutinemethod:: wait_closed()
Wait until the stream is closed.
Should be called after :meth:`close` to wait until the underlying
connection is closed.
.. versionadded:: 3.7
Examples
========
.. _asyncio-tcp-echo-client-streams:
TCP echo client using streams
-----------------------------
TCP echo client using the :func:`asyncio.open_connection` function::
import asyncio
async def tcp_echo_client(message):
reader, writer = await asyncio.open_connection(
'127.0.0.1', 8888)
print(f'Send: {message!r}')
writer.write(message.encode())
data = await reader.read(100)
print(f'Received: {data.decode()!r}')
print('Close the connection')
writer.close()
asyncio.run(tcp_echo_client('Hello World!'))
.. seealso::
The :ref:`TCP echo client protocol <asyncio_example_tcp_echo_client_protocol>`
example uses the low-level :meth:`loop.create_connection` method.
.. _asyncio-tcp-echo-server-streams:
TCP echo server using streams
-----------------------------
TCP echo server using the :func:`asyncio.start_server` function::
import asyncio
async def handle_echo(reader, writer):
data = await reader.read(100)
message = data.decode()
addr = writer.get_extra_info('peername')
print(f"Received {message!r} from {addr!r}")
print(f"Send: {message!r}")
writer.write(data)
await writer.drain()
print("Close the connection")
writer.close()
async def main():
server = await asyncio.start_server(
handle_echo, '127.0.0.1', 8888)
addr = server.sockets[0].getsockname()
print(f'Serving on {addr}')
async with server:
await server.serve_forever()
asyncio.run(main())
.. seealso::
The :ref:`TCP echo server protocol <asyncio_example_tcp_echo_server_protocol>`
example uses the :meth:`loop.create_server` method.
Get HTTP headers
----------------
Simple example querying HTTP headers of the URL passed on the command line::
import asyncio
import urllib.parse
import sys
async def print_http_headers(url):
url = urllib.parse.urlsplit(url)
if url.scheme == 'https':
reader, writer = await asyncio.open_connection(
url.hostname, 443, ssl=True)
else:
reader, writer = await asyncio.open_connection(
url.hostname, 80)
query = (
f"HEAD {url.path or '/'} HTTP/1.0\r\n"
f"Host: {url.hostname}\r\n"
f"\r\n"
)
writer.write(query.encode('latin-1'))
while True:
line = await reader.readline()
if not line:
break
line = line.decode('latin1').rstrip()
if line:
print(f'HTTP header> {line}')
# Ignore the body, close the socket
writer.close()
url = sys.argv[1]
asyncio.run(print_http_headers(url))
Usage::
python example.py http://example.com/path/page.html
or with HTTPS::
python example.py https://example.com/path/page.html
.. _asyncio_example_create_connection-streams:
Register an open socket to wait for data using streams
------------------------------------------------------
Coroutine waiting until a socket receives data using the
:func:`open_connection` function::
import asyncio
import socket
async def wait_for_data():
# Get a reference to the current event loop because
# we want to access low-level APIs.
loop = asyncio.get_running_loop()
# Create a pair of connected sockets.
rsock, wsock = socket.socketpair()
# Register the open socket to wait for data.
reader, writer = await asyncio.open_connection(sock=rsock)
# Simulate the reception of data from the network
loop.call_soon(wsock.send, 'abc'.encode())
# Wait for data
data = await reader.read(100)
# Got data, we are done: close the socket
print("Received:", data.decode())
writer.close()
# Close the second socket
wsock.close()
asyncio.run(wait_for_data())
.. seealso::
The :ref:`register an open socket to wait for data using a protocol
<asyncio_example_create_connection>` example uses a low-level protocol and
the :meth:`loop.create_connection` method.
The :ref:`watch a file descriptor for read events
<asyncio_example_watch_fd>` example uses the low-level
:meth:`loop.add_reader` method to watch a file descriptor.

371
web/python-docs/_sources/library/asyncio-subprocess.rst.txt Normal file
View File

@@ -0,0 +1,371 @@
.. currentmodule:: asyncio
.. _asyncio-subprocess:
============
Subprocesses
============
**Source code:** :source:`Lib/asyncio/subprocess.py`,
:source:`Lib/asyncio/base_subprocess.py`
----------------------------------------
This section describes high-level async/await asyncio APIs to
create and manage subprocesses.
.. _asyncio_example_subprocess_shell:
Here's an example of how asyncio can run a shell command and
obtain its result::
import asyncio
async def run(cmd):
proc = await asyncio.create_subprocess_shell(
cmd,
stdout=asyncio.subprocess.PIPE,
stderr=asyncio.subprocess.PIPE)
stdout, stderr = await proc.communicate()
print(f'[{cmd!r} exited with {proc.returncode}]')
if stdout:
print(f'[stdout]\n{stdout.decode()}')
if stderr:
print(f'[stderr]\n{stderr.decode()}')
asyncio.run(run('ls /zzz'))
will print::
['ls /zzz' exited with 1]
[stderr]
ls: /zzz: No such file or directory
Because all asyncio subprocess functions are asynchronous and asyncio
provides many tools to work with such functions, it is easy to execute
and monitor multiple subprocesses in parallel. It is indeed trivial
to modify the above example to run several commands simultaneously::
async def main():
await asyncio.gather(
run('ls /zzz'),
run('sleep 1; echo "hello"'))
asyncio.run(main())
See also the `Examples`_ subsection.
Creating Subprocesses
=====================
.. coroutinefunction:: create_subprocess_exec(program, *args, stdin=None, \
stdout=None, stderr=None, loop=None, \
limit=None, **kwds)
Create a subprocess.
The *limit* argument sets the buffer limit for :class:`StreamReader`
wrappers for :attr:`Process.stdout` and :attr:`Process.stderr`
(if :attr:`subprocess.PIPE` is passed to *stdout* and *stderr* arguments).
Return a :class:`~asyncio.subprocess.Process` instance.
See the documentation of :meth:`loop.subprocess_exec` for other
parameters.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
.. coroutinefunction:: create_subprocess_shell(cmd, stdin=None, \
stdout=None, stderr=None, loop=None, \
limit=None, **kwds)
Run the *cmd* shell command.
The *limit* argument sets the buffer limit for :class:`StreamReader`
wrappers for :attr:`Process.stdout` and :attr:`Process.stderr`
(if :attr:`subprocess.PIPE` is passed to *stdout* and *stderr* arguments).
Return a :class:`~asyncio.subprocess.Process` instance.
See the documentation of :meth:`loop.subprocess_shell` for other
parameters.
.. important::
It is the application's responsibility to ensure that all whitespace and
special characters are quoted appropriately to avoid `shell injection
<https://en.wikipedia.org/wiki/Shell_injection#Shell_injection>`_
vulnerabilities. The :func:`shlex.quote` function can be used to properly
escape whitespace and special shell characters in strings that are going
to be used to construct shell commands.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
.. note::
Subprocesses are available for Windows if a :class:`ProactorEventLoop` is
used. See :ref:`Subprocess Support on Windows <asyncio-windows-subprocess>`
for details.
.. seealso::
asyncio also has the following *low-level* APIs to work with subprocesses:
:meth:`loop.subprocess_exec`, :meth:`loop.subprocess_shell`,
:meth:`loop.connect_read_pipe`, :meth:`loop.connect_write_pipe`,
as well as the :ref:`Subprocess Transports <asyncio-subprocess-transports>`
and :ref:`Subprocess Protocols <asyncio-subprocess-protocols>`.
Constants
=========
.. data:: asyncio.subprocess.PIPE
Can be passed to the *stdin*, *stdout* or *stderr* parameters.
If *PIPE* is passed to *stdin* argument, the
:attr:`Process.stdin <asyncio.subprocess.Process.stdin>` attribute
will point to a :class:`StreamWriter` instance.
If *PIPE* is passed to *stdout* or *stderr* arguments, the
:attr:`Process.stdout <asyncio.subprocess.Process.stdout>` and
:attr:`Process.stderr <asyncio.subprocess.Process.stderr>`
attributes will point to :class:`StreamReader` instances.
.. data:: asyncio.subprocess.STDOUT
Special value that can be used as the *stderr* argument and indicates
that standard error should be redirected into standard output.
.. data:: asyncio.subprocess.DEVNULL
Special value that can be used as the *stdin*, *stdout* or *stderr* argument
to process creation functions. It indicates that the special file
:data:`os.devnull` will be used for the corresponding subprocess stream.
Interacting with Subprocesses
=============================
Both :func:`create_subprocess_exec` and :func:`create_subprocess_shell`
functions return instances of the *Process* class. *Process* is a high-level
wrapper that allows communicating with subprocesses and watching for
their completion.
.. class:: asyncio.subprocess.Process
An object that wraps OS processes created by the
:func:`create_subprocess_exec` and :func:`create_subprocess_shell`
functions.
This class is designed to have a similar API to the
:class:`subprocess.Popen` class, but there are some
notable differences:
* unlike Popen, Process instances do not have an equivalent to
the :meth:`~subprocess.Popen.poll` method;
* the :meth:`~asyncio.subprocess.Process.communicate` and
:meth:`~asyncio.subprocess.Process.wait` methods don't have a
*timeout* parameter: use the :func:`wait_for` function;
* the :meth:`Process.wait() <asyncio.subprocess.Process.wait>` method
is asynchronous, whereas :meth:`subprocess.Popen.wait` method
is implemented as a blocking busy loop;
* the *universal_newlines* parameter is not supported.
This class is :ref:`not thread safe <asyncio-multithreading>`.
See also the :ref:`Subprocess and Threads <asyncio-subprocess-threads>`
section.
.. coroutinemethod:: wait()
Wait for the child process to terminate.
Set and return the :attr:`returncode` attribute.
.. note::
This method can deadlock when using ``stdout=PIPE`` or
``stderr=PIPE`` and the child process generates so much output
that it blocks waiting for the OS pipe buffer to accept
more data. Use the :meth:`communicate` method when using pipes
to avoid this condition.
.. coroutinemethod:: communicate(input=None)
Interact with process:
1. send data to *stdin* (if *input* is not ``None``);
2. read data from *stdout* and *stderr*, until EOF is reached;
3. wait for process to terminate.
The optional *input* argument is the data (:class:`bytes` object)
that will be sent to the child process.
Return a tuple ``(stdout_data, stderr_data)``.
If either :exc:`BrokenPipeError` or :exc:`ConnectionResetError`
exception is raised when writing *input* into *stdin*, the
exception is ignored. This condition occurs when the process
exits before all data are written into *stdin*.
If it is desired to send data to the process' *stdin*,
the process needs to be created with ``stdin=PIPE``. Similarly,
to get anything other than ``None`` in the result tuple, the
process has to be created with ``stdout=PIPE`` and/or
``stderr=PIPE`` arguments.
Note, that the data read is buffered in memory, so do not use
this method if the data size is large or unlimited.
.. method:: send_signal(signal)
Sends the signal *signal* to the child process.
.. note::
On Windows, :py:data:`SIGTERM` is an alias for :meth:`terminate`.
``CTRL_C_EVENT`` and ``CTRL_BREAK_EVENT`` can be sent to processes
started with a *creationflags* parameter which includes
``CREATE_NEW_PROCESS_GROUP``.
.. method:: terminate()
Stop the child process.
On POSIX systems this method sends :py:data:`signal.SIGTERM` to the
child process.
On Windows the Win32 API function :c:func:`TerminateProcess` is
called to stop the child process.
.. method:: kill()
Kill the child process.
On POSIX systems this method sends :py:data:`SIGKILL` to the child
process.
On Windows this method is an alias for :meth:`terminate`.
.. attribute:: stdin
Standard input stream (:class:`StreamWriter`) or ``None``
if the process was created with ``stdin=None``.
.. attribute:: stdout
Standard output stream (:class:`StreamReader`) or ``None``
if the process was created with ``stdout=None``.
.. attribute:: stderr
Standard error stream (:class:`StreamReader`) or ``None``
if the process was created with ``stderr=None``.
.. warning::
Use the :meth:`communicate` method rather than
:attr:`process.stdin.write() <stdin>`,
:attr:`await process.stdout.read() <stdout>` or
:attr:`await process.stderr.read <stderr>`.
This avoids deadlocks due to streams pausing reading or writing
and blocking the child process.
.. attribute:: pid
Process identification number (PID).
Note that for processes created by the :func:`create_subprocess_shell`
function, this attribute is the PID of the spawned shell.
.. attribute:: returncode
Return code of the process when it exits.
A ``None`` value indicates that the process has not terminated yet.
A negative value ``-N`` indicates that the child was terminated
by signal ``N`` (POSIX only).
.. _asyncio-subprocess-threads:
Subprocess and Threads
----------------------
Standard asyncio event loop supports running subprocesses from different threads by
default.
On Windows subprocesses are provided by :class:`ProactorEventLoop` only (default),
:class:`SelectorEventLoop` has no subprocess support.
On UNIX *child watchers* are used for subprocess finish waiting, see
:ref:`asyncio-watchers` for more info.
.. versionchanged:: 3.8
UNIX switched to use :class:`ThreadedChildWatcher` for spawning subprocesses from
different threads without any limitation.
Spawning a subprocess with *inactive* current child watcher raises
:exc:`RuntimeError`.
Note that alternative event loop implementations might have own limitations;
please refer to their documentation.
.. seealso::
The :ref:`Concurrency and multithreading in asyncio
<asyncio-multithreading>` section.
Examples
--------
An example using the :class:`~asyncio.subprocess.Process` class to
control a subprocess and the :class:`StreamReader` class to read from
its standard output.
.. _asyncio_example_create_subprocess_exec:
The subprocess is created by the :func:`create_subprocess_exec`
function::
import asyncio
import sys
async def get_date():
code = 'import datetime; print(datetime.datetime.now())'
# Create the subprocess; redirect the standard output
# into a pipe.
proc = await asyncio.create_subprocess_exec(
sys.executable, '-c', code,
stdout=asyncio.subprocess.PIPE)
# Read one line of output.
data = await proc.stdout.readline()
line = data.decode('ascii').rstrip()
# Wait for the subprocess exit.
await proc.wait()
return line
date = asyncio.run(get_date())
print(f"Current date: {date}")
See also the :ref:`same example <asyncio_example_subprocess_proto>`
written using low-level APIs.

354
web/python-docs/_sources/library/asyncio-sync.rst.txt Normal file
View File

@@ -0,0 +1,354 @@
.. currentmodule:: asyncio
.. _asyncio-sync:
==========================
Synchronization Primitives
==========================
**Source code:** :source:`Lib/asyncio/locks.py`
-----------------------------------------------
asyncio synchronization primitives are designed to be similar to
those of the :mod:`threading` module with two important caveats:
* asyncio primitives are not thread-safe, therefore they should not
be used for OS thread synchronization (use :mod:`threading` for
that);
* methods of these synchronization primitives do not accept the *timeout*
argument; use the :func:`asyncio.wait_for` function to perform
operations with timeouts.
asyncio has the following basic synchronization primitives:
* :class:`Lock`
* :class:`Event`
* :class:`Condition`
* :class:`Semaphore`
* :class:`BoundedSemaphore`
---------
Lock
====
.. class:: Lock(\*, loop=None)
Implements a mutex lock for asyncio tasks. Not thread-safe.
An asyncio lock can be used to guarantee exclusive access to a
shared resource.
The preferred way to use a Lock is an :keyword:`async with`
statement::
lock = asyncio.Lock()
# ... later
async with lock:
# access shared state
which is equivalent to::
lock = asyncio.Lock()
# ... later
await lock.acquire()
try:
# access shared state
finally:
lock.release()
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
.. coroutinemethod:: acquire()
Acquire the lock.
This method waits until the lock is *unlocked*, sets it to
*locked* and returns ``True``.
When more than one coroutine is blocked in :meth:`acquire`
waiting for the lock to be unlocked, only one coroutine
eventually proceeds.
Acquiring a lock is *fair*: the coroutine that proceeds will be
the first coroutine that started waiting on the lock.
.. method:: release()
Release the lock.
When the lock is *locked*, reset it to *unlocked* and return.
If the lock is *unlocked*, a :exc:`RuntimeError` is raised.
.. method:: locked()
Return ``True`` if the lock is *locked*.
Event
=====
.. class:: Event(\*, loop=None)
An event object. Not thread-safe.
An asyncio event can be used to notify multiple asyncio tasks
that some event has happened.
An Event object manages an internal flag that can be set to *true*
with the :meth:`~Event.set` method and reset to *false* with the
:meth:`clear` method. The :meth:`~Event.wait` method blocks until the
flag is set to *true*. The flag is set to *false* initially.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
.. _asyncio_example_sync_event:
Example::
async def waiter(event):
print('waiting for it ...')
await event.wait()
print('... got it!')
async def main():
# Create an Event object.
event = asyncio.Event()
# Spawn a Task to wait until 'event' is set.
waiter_task = asyncio.create_task(waiter(event))
# Sleep for 1 second and set the event.
await asyncio.sleep(1)
event.set()
# Wait until the waiter task is finished.
await waiter_task
asyncio.run(main())
.. coroutinemethod:: wait()
Wait until the event is set.
If the event is set, return ``True`` immediately.
Otherwise block until another task calls :meth:`~Event.set`.
.. method:: set()
Set the event.
All tasks waiting for event to be set will be immediately
awakened.
.. method:: clear()
Clear (unset) the event.
Tasks awaiting on :meth:`~Event.wait` will now block until the
:meth:`~Event.set` method is called again.
.. method:: is_set()
Return ``True`` if the event is set.
Condition
=========
.. class:: Condition(lock=None, \*, loop=None)
A Condition object. Not thread-safe.
An asyncio condition primitive can be used by a task to wait for
some event to happen and then get exclusive access to a shared
resource.
In essence, a Condition object combines the functionality
of an :class:`Event` and a :class:`Lock`. It is possible to have
multiple Condition objects share one Lock, which allows coordinating
exclusive access to a shared resource between different tasks
interested in particular states of that shared resource.
The optional *lock* argument must be a :class:`Lock` object or
``None``. In the latter case a new Lock object is created
automatically.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
The preferred way to use a Condition is an :keyword:`async with`
statement::
cond = asyncio.Condition()
# ... later
async with cond:
await cond.wait()
which is equivalent to::
cond = asyncio.Condition()
# ... later
await cond.acquire()
try:
await cond.wait()
finally:
cond.release()
.. coroutinemethod:: acquire()
Acquire the underlying lock.
This method waits until the underlying lock is *unlocked*,
sets it to *locked* and returns ``True``.
.. method:: notify(n=1)
Wake up at most *n* tasks (1 by default) waiting on this
condition. The method is no-op if no tasks are waiting.
The lock must be acquired before this method is called and
released shortly after. If called with an *unlocked* lock
a :exc:`RuntimeError` error is raised.
.. method:: locked()
Return ``True`` if the underlying lock is acquired.
.. method:: notify_all()
Wake up all tasks waiting on this condition.
This method acts like :meth:`notify`, but wakes up all waiting
tasks.
The lock must be acquired before this method is called and
released shortly after. If called with an *unlocked* lock
a :exc:`RuntimeError` error is raised.
.. method:: release()
Release the underlying lock.
When invoked on an unlocked lock, a :exc:`RuntimeError` is
raised.
.. coroutinemethod:: wait()
Wait until notified.
If the calling task has not acquired the lock when this method is
called, a :exc:`RuntimeError` is raised.
This method releases the underlying lock, and then blocks until
it is awakened by a :meth:`notify` or :meth:`notify_all` call.
Once awakened, the Condition re-acquires its lock and this method
returns ``True``.
.. coroutinemethod:: wait_for(predicate)
Wait until a predicate becomes *true*.
The predicate must be a callable which result will be
interpreted as a boolean value. The final value is the
return value.
Semaphore
=========
.. class:: Semaphore(value=1, \*, loop=None)
A Semaphore object. Not thread-safe.
A semaphore manages an internal counter which is decremented by each
:meth:`acquire` call and incremented by each :meth:`release` call.
The counter can never go below zero; when :meth:`acquire` finds
that it is zero, it blocks, waiting until some task calls
:meth:`release`.
The optional *value* argument gives the initial value for the
internal counter (``1`` by default). If the given value is
less than ``0`` a :exc:`ValueError` is raised.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
The preferred way to use a Semaphore is an :keyword:`async with`
statement::
sem = asyncio.Semaphore(10)
# ... later
async with sem:
# work with shared resource
which is equivalent to::
sem = asyncio.Semaphore(10)
# ... later
await sem.acquire()
try:
# work with shared resource
finally:
sem.release()
.. coroutinemethod:: acquire()
Acquire a semaphore.
If the internal counter is greater than zero, decrement
it by one and return ``True`` immediately. If it is zero, wait
until a :meth:`release` is called and return ``True``.
.. method:: locked()
Returns ``True`` if semaphore can not be acquired immediately.
.. method:: release()
Release a semaphore, incrementing the internal counter by one.
Can wake up a task waiting to acquire the semaphore.
Unlike :class:`BoundedSemaphore`, :class:`Semaphore` allows
making more ``release()`` calls than ``acquire()`` calls.
BoundedSemaphore
================
.. class:: BoundedSemaphore(value=1, \*, loop=None)
A bounded semaphore object. Not thread-safe.
Bounded Semaphore is a version of :class:`Semaphore` that raises
a :exc:`ValueError` in :meth:`~Semaphore.release` if it
increases the internal counter above the initial *value*.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
---------
.. deprecated:: 3.7
Acquiring a lock using ``await lock`` or ``yield from lock`` and/or
:keyword:`with` statement (``with await lock``, ``with (yield from
lock)``) is deprecated. Use ``async with lock`` instead.

986
web/python-docs/_sources/library/asyncio-task.rst.txt Normal file
View File

@@ -0,0 +1,986 @@
.. currentmodule:: asyncio
====================
Coroutines and Tasks
====================
This section outlines high-level asyncio APIs to work with coroutines
and Tasks.
.. contents::
:depth: 1
:local:
.. _coroutine:
Coroutines
==========
:term:`Coroutines <coroutine>` declared with the async/await syntax is the
preferred way of writing asyncio applications. For example, the following
snippet of code (requires Python 3.7+) prints "hello", waits 1 second,
and then prints "world"::
>>> import asyncio
>>> async def main():
... print('hello')
... await asyncio.sleep(1)
... print('world')
>>> asyncio.run(main())
hello
world
Note that simply calling a coroutine will not schedule it to
be executed::
>>> main()
<coroutine object main at 0x1053bb7c8>
To actually run a coroutine, asyncio provides three main mechanisms:
* The :func:`asyncio.run` function to run the top-level
entry point "main()" function (see the above example.)
* Awaiting on a coroutine. The following snippet of code will
print "hello" after waiting for 1 second, and then print "world"
after waiting for *another* 2 seconds::
import asyncio
import time
async def say_after(delay, what):
await asyncio.sleep(delay)
print(what)
async def main():
print(f"started at {time.strftime('%X')}")
await say_after(1, 'hello')
await say_after(2, 'world')
print(f"finished at {time.strftime('%X')}")
asyncio.run(main())
Expected output::
started at 17:13:52
hello
world
finished at 17:13:55
* The :func:`asyncio.create_task` function to run coroutines
concurrently as asyncio :class:`Tasks <Task>`.
Let's modify the above example and run two ``say_after`` coroutines
*concurrently*::
async def main():
task1 = asyncio.create_task(
say_after(1, 'hello'))
task2 = asyncio.create_task(
say_after(2, 'world'))
print(f"started at {time.strftime('%X')}")
# Wait until both tasks are completed (should take
# around 2 seconds.)
await task1
await task2
print(f"finished at {time.strftime('%X')}")
Note that expected output now shows that the snippet runs
1 second faster than before::
started at 17:14:32
hello
world
finished at 17:14:34
.. _asyncio-awaitables:
Awaitables
==========
We say that an object is an **awaitable** object if it can be used
in an :keyword:`await` expression. Many asyncio APIs are designed to
accept awaitables.
There are three main types of *awaitable* objects:
**coroutines**, **Tasks**, and **Futures**.
.. rubric:: Coroutines
Python coroutines are *awaitables* and therefore can be awaited from
other coroutines::
import asyncio
async def nested():
return 42
async def main():
# Nothing happens if we just call "nested()".
# A coroutine object is created but not awaited,
# so it *won't run at all*.
nested()
# Let's do it differently now and await it:
print(await nested()) # will print "42".
asyncio.run(main())
.. important::
In this documentation the term "coroutine" can be used for
two closely related concepts:
* a *coroutine function*: an :keyword:`async def` function;
* a *coroutine object*: an object returned by calling a
*coroutine function*.
asyncio also supports legacy :ref:`generator-based
<asyncio_generator_based_coro>` coroutines.
.. rubric:: Tasks
*Tasks* are used to schedule coroutines *concurrently*.
When a coroutine is wrapped into a *Task* with functions like
:func:`asyncio.create_task` the coroutine is automatically
scheduled to run soon::
import asyncio
async def nested():
return 42
async def main():
# Schedule nested() to run soon concurrently
# with "main()".
task = asyncio.create_task(nested())
# "task" can now be used to cancel "nested()", or
# can simply be awaited to wait until it is complete:
await task
asyncio.run(main())
.. rubric:: Futures
A :class:`Future` is a special **low-level** awaitable object that
represents an **eventual result** of an asynchronous operation.
When a Future object is *awaited* it means that the coroutine will
wait until the Future is resolved in some other place.
Future objects in asyncio are needed to allow callback-based code
to be used with async/await.
Normally **there is no need** to create Future objects at the
application level code.
Future objects, sometimes exposed by libraries and some asyncio
APIs, can be awaited::
async def main():
await function_that_returns_a_future_object()
# this is also valid:
await asyncio.gather(
function_that_returns_a_future_object(),
some_python_coroutine()
)
A good example of a low-level function that returns a Future object
is :meth:`loop.run_in_executor`.
Running an asyncio Program
==========================
.. function:: run(coro, *, debug=False)
Execute the :term:`coroutine` *coro* and return the result.
This function runs the passed coroutine, taking care of
managing the asyncio event loop and *finalizing asynchronous
generators*.
This function cannot be called when another asyncio event loop is
running in the same thread.
If *debug* is ``True``, the event loop will be run in debug mode.
This function always creates a new event loop and closes it at
the end. It should be used as a main entry point for asyncio
programs, and should ideally only be called once.
Example::
async def main():
await asyncio.sleep(1)
print('hello')
asyncio.run(main())
.. versionadded:: 3.7
.. note::
The source code for ``asyncio.run()`` can be found in
:source:`Lib/asyncio/runners.py`.
Creating Tasks
==============
.. function:: create_task(coro, *, name=None)
Wrap the *coro* :ref:`coroutine <coroutine>` into a :class:`Task`
and schedule its execution. Return the Task object.
If *name* is not ``None``, it is set as the name of the task using
:meth:`Task.set_name`.
The task is executed in the loop returned by :func:`get_running_loop`,
:exc:`RuntimeError` is raised if there is no running loop in
current thread.
This function has been **added in Python 3.7**. Prior to
Python 3.7, the low-level :func:`asyncio.ensure_future` function
can be used instead::
async def coro():
...
# In Python 3.7+
task = asyncio.create_task(coro())
...
# This works in all Python versions but is less readable
task = asyncio.ensure_future(coro())
...
.. versionadded:: 3.7
.. versionchanged:: 3.8
Added the ``name`` parameter.
Sleeping
========
.. coroutinefunction:: sleep(delay, result=None, \*, loop=None)
Block for *delay* seconds.
If *result* is provided, it is returned to the caller
when the coroutine completes.
``sleep()`` always suspends the current task, allowing other tasks
to run.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
.. _asyncio_example_sleep:
Example of coroutine displaying the current date every second
for 5 seconds::
import asyncio
import datetime
async def display_date():
loop = asyncio.get_running_loop()
end_time = loop.time() + 5.0
while True:
print(datetime.datetime.now())
if (loop.time() + 1.0) >= end_time:
break
await asyncio.sleep(1)
asyncio.run(display_date())
Running Tasks Concurrently
==========================
.. awaitablefunction:: gather(*aws, loop=None, return_exceptions=False)
Run :ref:`awaitable objects <asyncio-awaitables>` in the *aws*
sequence *concurrently*.
If any awaitable in *aws* is a coroutine, it is automatically
scheduled as a Task.
If all awaitables are completed successfully, the result is an
aggregate list of returned values. The order of result values
corresponds to the order of awaitables in *aws*.
If *return_exceptions* is ``False`` (default), the first
raised exception is immediately propagated to the task that
awaits on ``gather()``. Other awaitables in the *aws* sequence
**won't be cancelled** and will continue to run.
If *return_exceptions* is ``True``, exceptions are treated the
same as successful results, and aggregated in the result list.
If ``gather()`` is *cancelled*, all submitted awaitables
(that have not completed yet) are also *cancelled*.
If any Task or Future from the *aws* sequence is *cancelled*, it is
treated as if it raised :exc:`CancelledError` -- the ``gather()``
call is **not** cancelled in this case. This is to prevent the
cancellation of one submitted Task/Future to cause other
Tasks/Futures to be cancelled.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
.. _asyncio_example_gather:
Example::
import asyncio
async def factorial(name, number):
f = 1
for i in range(2, number + 1):
print(f"Task {name}: Compute factorial({i})...")
await asyncio.sleep(1)
f *= i
print(f"Task {name}: factorial({number}) = {f}")
async def main():
# Schedule three calls *concurrently*:
await asyncio.gather(
factorial("A", 2),
factorial("B", 3),
factorial("C", 4),
)
asyncio.run(main())
# Expected output:
#
# Task A: Compute factorial(2)...
# Task B: Compute factorial(2)...
# Task C: Compute factorial(2)...
# Task A: factorial(2) = 2
# Task B: Compute factorial(3)...
# Task C: Compute factorial(3)...
# Task B: factorial(3) = 6
# Task C: Compute factorial(4)...
# Task C: factorial(4) = 24
.. note::
If *return_exceptions* is False, cancelling gather() after it
has been marked done won't cancel any submitted awaitables.
For instance, gather can be marked done after propagating an
exception to the caller, therefore, calling ``gather.cancel()``
after catching an exception (raised by one of the awaitables) from
gather won't cancel any other awaitables.
.. versionchanged:: 3.7
If the *gather* itself is cancelled, the cancellation is
propagated regardless of *return_exceptions*.
Shielding From Cancellation
===========================
.. awaitablefunction:: shield(aw, \*, loop=None)
Protect an :ref:`awaitable object <asyncio-awaitables>`
from being :meth:`cancelled <Task.cancel>`.
If *aw* is a coroutine it is automatically scheduled as a Task.
The statement::
res = await shield(something())
is equivalent to::
res = await something()
*except* that if the coroutine containing it is cancelled, the
Task running in ``something()`` is not cancelled. From the point
of view of ``something()``, the cancellation did not happen.
Although its caller is still cancelled, so the "await" expression
still raises a :exc:`CancelledError`.
If ``something()`` is cancelled by other means (i.e. from within
itself) that would also cancel ``shield()``.
If it is desired to completely ignore cancellation (not recommended)
the ``shield()`` function should be combined with a try/except
clause, as follows::
try:
res = await shield(something())
except CancelledError:
res = None
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
Timeouts
========
.. coroutinefunction:: wait_for(aw, timeout, \*, loop=None)
Wait for the *aw* :ref:`awaitable <asyncio-awaitables>`
to complete with a timeout.
If *aw* is a coroutine it is automatically scheduled as a Task.
*timeout* can either be ``None`` or a float or int number of seconds
to wait for. If *timeout* is ``None``, block until the future
completes.
If a timeout occurs, it cancels the task and raises
:exc:`asyncio.TimeoutError`.
To avoid the task :meth:`cancellation <Task.cancel>`,
wrap it in :func:`shield`.
The function will wait until the future is actually cancelled,
so the total wait time may exceed the *timeout*.
If the wait is cancelled, the future *aw* is also cancelled.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
.. _asyncio_example_waitfor:
Example::
async def eternity():
# Sleep for one hour
await asyncio.sleep(3600)
print('yay!')
async def main():
# Wait for at most 1 second
try:
await asyncio.wait_for(eternity(), timeout=1.0)
except asyncio.TimeoutError:
print('timeout!')
asyncio.run(main())
# Expected output:
#
# timeout!
.. versionchanged:: 3.7
When *aw* is cancelled due to a timeout, ``wait_for`` waits
for *aw* to be cancelled. Previously, it raised
:exc:`asyncio.TimeoutError` immediately.
Waiting Primitives
==================
.. coroutinefunction:: wait(aws, *, loop=None, timeout=None,\
return_when=ALL_COMPLETED)
Run :ref:`awaitable objects <asyncio-awaitables>` in the *aws*
iterable concurrently and block until the condition specified
by *return_when*.
Returns two sets of Tasks/Futures: ``(done, pending)``.
Usage::
done, pending = await asyncio.wait(aws)
*timeout* (a float or int), if specified, can be used to control
the maximum number of seconds to wait before returning.
Note that this function does not raise :exc:`asyncio.TimeoutError`.
Futures or Tasks that aren't done when the timeout occurs are simply
returned in the second set.
*return_when* indicates when this function should return. It must
be one of the following constants:
.. tabularcolumns:: |l|L|
+-----------------------------+----------------------------------------+
| Constant | Description |
+=============================+========================================+
| :const:`FIRST_COMPLETED` | The function will return when any |
| | future finishes or is cancelled. |
+-----------------------------+----------------------------------------+
| :const:`FIRST_EXCEPTION` | The function will return when any |
| | future finishes by raising an |
| | exception. If no future raises an |
| | exception then it is equivalent to |
| | :const:`ALL_COMPLETED`. |
+-----------------------------+----------------------------------------+
| :const:`ALL_COMPLETED` | The function will return when all |
| | futures finish or are cancelled. |
+-----------------------------+----------------------------------------+
Unlike :func:`~asyncio.wait_for`, ``wait()`` does not cancel the
futures when a timeout occurs.
.. deprecated:: 3.8
If any awaitable in *aws* is a coroutine, it is automatically
scheduled as a Task. Passing coroutines objects to
``wait()`` directly is deprecated as it leads to
:ref:`confusing behavior <asyncio_example_wait_coroutine>`.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
.. _asyncio_example_wait_coroutine:
.. note::
``wait()`` schedules coroutines as Tasks automatically and later
returns those implicitly created Task objects in ``(done, pending)``
sets. Therefore the following code won't work as expected::
async def foo():
return 42
coro = foo()
done, pending = await asyncio.wait({coro})
if coro in done:
# This branch will never be run!
Here is how the above snippet can be fixed::
async def foo():
return 42
task = asyncio.create_task(foo())
done, pending = await asyncio.wait({task})
if task in done:
# Everything will work as expected now.
.. deprecated:: 3.8
Passing coroutine objects to ``wait()`` directly is
deprecated.
.. function:: as_completed(aws, *, loop=None, timeout=None)
Run :ref:`awaitable objects <asyncio-awaitables>` in the *aws*
iterable concurrently. Return an iterator of coroutines.
Each coroutine returned can be awaited to get the earliest next
result from the iterable of the remaining awaitables.
Raises :exc:`asyncio.TimeoutError` if the timeout occurs before
all Futures are done.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
Example::
for coro in as_completed(aws):
earliest_result = await coro
# ...
Scheduling From Other Threads
=============================
.. function:: run_coroutine_threadsafe(coro, loop)
Submit a coroutine to the given event loop. Thread-safe.
Return a :class:`concurrent.futures.Future` to wait for the result
from another OS thread.
This function is meant to be called from a different OS thread
than the one where the event loop is running. Example::
# Create a coroutine
coro = asyncio.sleep(1, result=3)
# Submit the coroutine to a given loop
future = asyncio.run_coroutine_threadsafe(coro, loop)
# Wait for the result with an optional timeout argument
assert future.result(timeout) == 3
If an exception is raised in the coroutine, the returned Future
will be notified. It can also be used to cancel the task in
the event loop::
try:
result = future.result(timeout)
except asyncio.TimeoutError:
print('The coroutine took too long, cancelling the task...')
future.cancel()
except Exception as exc:
print(f'The coroutine raised an exception: {exc!r}')
else:
print(f'The coroutine returned: {result!r}')
See the :ref:`concurrency and multithreading <asyncio-multithreading>`
section of the documentation.
Unlike other asyncio functions this function requires the *loop*
argument to be passed explicitly.
.. versionadded:: 3.5.1
Introspection
=============
.. function:: current_task(loop=None)
Return the currently running :class:`Task` instance, or ``None`` if
no task is running.
If *loop* is ``None`` :func:`get_running_loop` is used to get
the current loop.
.. versionadded:: 3.7
.. function:: all_tasks(loop=None)
Return a set of not yet finished :class:`Task` objects run by
the loop.
If *loop* is ``None``, :func:`get_running_loop` is used for getting
current loop.
.. versionadded:: 3.7
Task Object
===========
.. class:: Task(coro, *, loop=None, name=None)
A :class:`Future-like <Future>` object that runs a Python
:ref:`coroutine <coroutine>`. Not thread-safe.
Tasks are used to run coroutines in event loops.
If a coroutine awaits on a Future, the Task suspends
the execution of the coroutine and waits for the completion
of the Future. When the Future is *done*, the execution of
the wrapped coroutine resumes.
Event loops use cooperative scheduling: an event loop runs
one Task at a time. While a Task awaits for the completion of a
Future, the event loop runs other Tasks, callbacks, or performs
IO operations.
Use the high-level :func:`asyncio.create_task` function to create
Tasks, or the low-level :meth:`loop.create_task` or
:func:`ensure_future` functions. Manual instantiation of Tasks
is discouraged.
To cancel a running Task use the :meth:`cancel` method. Calling it
will cause the Task to throw a :exc:`CancelledError` exception into
the wrapped coroutine. If a coroutine is awaiting on a Future
object during cancellation, the Future object will be cancelled.
:meth:`cancelled` can be used to check if the Task was cancelled.
The method returns ``True`` if the wrapped coroutine did not
suppress the :exc:`CancelledError` exception and was actually
cancelled.
:class:`asyncio.Task` inherits from :class:`Future` all of its
APIs except :meth:`Future.set_result` and
:meth:`Future.set_exception`.
Tasks support the :mod:`contextvars` module. When a Task
is created it copies the current context and later runs its
coroutine in the copied context.
.. versionchanged:: 3.7
Added support for the :mod:`contextvars` module.
.. versionchanged:: 3.8
Added the ``name`` parameter.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
.. method:: cancel()
Request the Task to be cancelled.
This arranges for a :exc:`CancelledError` exception to be thrown
into the wrapped coroutine on the next cycle of the event loop.
The coroutine then has a chance to clean up or even deny the
request by suppressing the exception with a :keyword:`try` ...
... ``except CancelledError`` ... :keyword:`finally` block.
Therefore, unlike :meth:`Future.cancel`, :meth:`Task.cancel` does
not guarantee that the Task will be cancelled, although
suppressing cancellation completely is not common and is actively
discouraged.
.. _asyncio_example_task_cancel:
The following example illustrates how coroutines can intercept
the cancellation request::
async def cancel_me():
print('cancel_me(): before sleep')
try:
# Wait for 1 hour
await asyncio.sleep(3600)
except asyncio.CancelledError:
print('cancel_me(): cancel sleep')
raise
finally:
print('cancel_me(): after sleep')
async def main():
# Create a "cancel_me" Task
task = asyncio.create_task(cancel_me())
# Wait for 1 second
await asyncio.sleep(1)
task.cancel()
try:
await task
except asyncio.CancelledError:
print("main(): cancel_me is cancelled now")
asyncio.run(main())
# Expected output:
#
# cancel_me(): before sleep
# cancel_me(): cancel sleep
# cancel_me(): after sleep
# main(): cancel_me is cancelled now
.. method:: cancelled()
Return ``True`` if the Task is *cancelled*.
The Task is *cancelled* when the cancellation was requested with
:meth:`cancel` and the wrapped coroutine propagated the
:exc:`CancelledError` exception thrown into it.
.. method:: done()
Return ``True`` if the Task is *done*.
A Task is *done* when the wrapped coroutine either returned
a value, raised an exception, or the Task was cancelled.
.. method:: result()
Return the result of the Task.
If the Task is *done*, the result of the wrapped coroutine
is returned (or if the coroutine raised an exception, that
exception is re-raised.)
If the Task has been *cancelled*, this method raises
a :exc:`CancelledError` exception.
If the Task's result isn't yet available, this method raises
a :exc:`InvalidStateError` exception.
.. method:: exception()
Return the exception of the Task.
If the wrapped coroutine raised an exception that exception
is returned. If the wrapped coroutine returned normally
this method returns ``None``.
If the Task has been *cancelled*, this method raises a
:exc:`CancelledError` exception.
If the Task isn't *done* yet, this method raises an
:exc:`InvalidStateError` exception.
.. method:: add_done_callback(callback, *, context=None)
Add a callback to be run when the Task is *done*.
This method should only be used in low-level callback-based code.
See the documentation of :meth:`Future.add_done_callback`
for more details.
.. method:: remove_done_callback(callback)
Remove *callback* from the callbacks list.
This method should only be used in low-level callback-based code.
See the documentation of :meth:`Future.remove_done_callback`
for more details.
.. method:: get_stack(*, limit=None)
Return the list of stack frames for this Task.
If the wrapped coroutine is not done, this returns the stack
where it is suspended. If the coroutine has completed
successfully or was cancelled, this returns an empty list.
If the coroutine was terminated by an exception, this returns
the list of traceback frames.
The frames are always ordered from oldest to newest.
Only one stack frame is returned for a suspended coroutine.
The optional *limit* argument sets the maximum number of frames
to return; by default all available frames are returned.
The ordering of the returned list differs depending on whether
a stack or a traceback is returned: the newest frames of a
stack are returned, but the oldest frames of a traceback are
returned. (This matches the behavior of the traceback module.)
.. method:: print_stack(*, limit=None, file=None)
Print the stack or traceback for this Task.
This produces output similar to that of the traceback module
for the frames retrieved by :meth:`get_stack`.
The *limit* argument is passed to :meth:`get_stack` directly.
The *file* argument is an I/O stream to which the output
is written; by default output is written to :data:`sys.stderr`.
.. method:: get_coro()
Return the coroutine object wrapped by the :class:`Task`.
.. versionadded:: 3.8
.. method:: get_name()
Return the name of the Task.
If no name has been explicitly assigned to the Task, the default
asyncio Task implementation generates a default name during
instantiation.
.. versionadded:: 3.8
.. method:: set_name(value)
Set the name of the Task.
The *value* argument can be any object, which is then
converted to a string.
In the default Task implementation, the name will be visible
in the :func:`repr` output of a task object.
.. versionadded:: 3.8
.. classmethod:: all_tasks(loop=None)
Return a set of all tasks for an event loop.
By default all tasks for the current event loop are returned.
If *loop* is ``None``, the :func:`get_event_loop` function
is used to get the current loop.
.. deprecated-removed:: 3.7 3.9
Do not call this as a task method. Use the :func:`asyncio.all_tasks`
function instead.
.. classmethod:: current_task(loop=None)
Return the currently running task or ``None``.
If *loop* is ``None``, the :func:`get_event_loop` function
is used to get the current loop.
.. deprecated-removed:: 3.7 3.9
Do not call this as a task method. Use the
:func:`asyncio.current_task` function instead.
.. _asyncio_generator_based_coro:
Generator-based Coroutines
==========================
.. note::
Support for generator-based coroutines is **deprecated** and
is scheduled for removal in Python 3.10.
Generator-based coroutines predate async/await syntax. They are
Python generators that use ``yield from`` expressions to await
on Futures and other coroutines.
Generator-based coroutines should be decorated with
:func:`@asyncio.coroutine <asyncio.coroutine>`, although this is not
enforced.
.. decorator:: coroutine
Decorator to mark generator-based coroutines.
This decorator enables legacy generator-based coroutines to be
compatible with async/await code::
@asyncio.coroutine
def old_style_coroutine():
yield from asyncio.sleep(1)
async def main():
await old_style_coroutine()
This decorator should not be used for :keyword:`async def`
coroutines.
.. deprecated-removed:: 3.8 3.10
Use :keyword:`async def` instead.
.. function:: iscoroutine(obj)
Return ``True`` if *obj* is a :ref:`coroutine object <coroutine>`.
This method is different from :func:`inspect.iscoroutine` because
it returns ``True`` for generator-based coroutines.
.. function:: iscoroutinefunction(func)
Return ``True`` if *func* is a :ref:`coroutine function
<coroutine>`.
This method is different from :func:`inspect.iscoroutinefunction`
because it returns ``True`` for generator-based coroutine functions
decorated with :func:`@coroutine <coroutine>`.

116
web/python-docs/_sources/library/asyncio.rst.txt Normal file
View File

@@ -0,0 +1,116 @@
:mod:`asyncio` --- Asynchronous I/O
===================================
.. module:: asyncio
:synopsis: Asynchronous I/O.
-------------------------------
.. sidebar:: Hello World!
::
import asyncio
async def main():
print('Hello ...')
await asyncio.sleep(1)
print('... World!')
# Python 3.7+
asyncio.run(main())
asyncio is a library to write **concurrent** code using
the **async/await** syntax.
asyncio is used as a foundation for multiple Python asynchronous
frameworks that provide high-performance network and web-servers,
database connection libraries, distributed task queues, etc.
asyncio is often a perfect fit for IO-bound and high-level
**structured** network code.
asyncio provides a set of **high-level** APIs to:
* :ref:`run Python coroutines <coroutine>` concurrently and
have full control over their execution;
* perform :ref:`network IO and IPC <asyncio-streams>`;
* control :ref:`subprocesses <asyncio-subprocess>`;
* distribute tasks via :ref:`queues <asyncio-queues>`;
* :ref:`synchronize <asyncio-sync>` concurrent code;
Additionally, there are **low-level** APIs for
*library and framework developers* to:
* create and manage :ref:`event loops <asyncio-event-loop>`, which
provide asynchronous APIs for :meth:`networking <loop.create_server>`,
running :meth:`subprocesses <loop.subprocess_exec>`,
handling :meth:`OS signals <loop.add_signal_handler>`, etc;
* implement efficient protocols using
:ref:`transports <asyncio-transports-protocols>`;
* :ref:`bridge <asyncio-futures>` callback-based libraries and code
with async/await syntax.
.. _asyncio-cli:
.. rubric:: asyncio REPL
You can experiment with an ``asyncio`` concurrent context in the REPL:
.. code-block:: pycon
$ python -m asyncio
asyncio REPL ...
Use "await" directly instead of "asyncio.run()".
Type "help", "copyright", "credits" or "license" for more information.
>>> import asyncio
>>> await asyncio.sleep(10, result='hello')
'hello'
.. audit-event:: cpython.run_stdin "" ""
.. versionchanged:: 3.8.20
Emits audit events.
.. We use the "rubric" directive here to avoid creating
the "Reference" subsection in the TOC.
.. rubric:: Reference
.. toctree::
:caption: High-level APIs
:maxdepth: 1
asyncio-task.rst
asyncio-stream.rst
asyncio-sync.rst
asyncio-subprocess.rst
asyncio-queue.rst
asyncio-exceptions.rst
.. toctree::
:caption: Low-level APIs
:maxdepth: 1
asyncio-eventloop.rst
asyncio-future.rst
asyncio-protocol.rst
asyncio-policy.rst
asyncio-platforms.rst
.. toctree::
:caption: Guides and Tutorials
:maxdepth: 1
asyncio-api-index.rst
asyncio-llapi-index.rst
asyncio-dev.rst
.. note::
The source code for asyncio can be found in :source:`Lib/asyncio/`.

360
web/python-docs/_sources/library/asyncore.rst.txt Normal file
View File

@@ -0,0 +1,360 @@
: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`
.. deprecated:: 3.6
Please use :mod:`asyncio` instead.
--------------
.. note::
This module exists for backwards compatibility only. For new code we
recommend using :mod:`asyncio`.
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_accepted()``| 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. Deprecated in version 3.2; use
:meth:`handle_accepted` instead.
.. deprecated:: 3.2
.. method:: handle_accepted(sock, addr)
Called on listening channels (passive openers) when a connection has been
established with a new remote endpoint that has issued a :meth:`connect`
call for the local endpoint. *sock* is a *new* socket object usable to
send and receive data on the connection, and *addr* is the address
bound to the socket on the other end of the connection.
.. versionadded:: 3.2
.. 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=socket.AF_INET, type=socket.SOCK_STREAM)
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.
.. versionchanged:: 3.3
*family* and *type* arguments can be omitted.
.. 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 bytes object implies that the channel has been closed from the
other end.
Note that :meth:`recv` may raise :exc:`BlockingIOError` , 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 :term:`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
class HTTPClient(asyncore.dispatcher):
def __init__(self, host, path):
asyncore.dispatcher.__init__(self)
self.create_socket()
self.connect( (host, 80) )
self.buffer = bytes('GET %s HTTP/1.0\r\nHost: %s\r\n\r\n' %
(path, host), 'ascii')
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
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()
self.set_reuse_addr()
self.bind((host, port))
self.listen(5)
def handle_accepted(self, sock, addr):
print('Incoming connection from %s' % repr(addr))
handler = EchoHandler(sock)
server = EchoServer('localhost', 8080)
asyncore.loop()

112
web/python-docs/_sources/library/atexit.rst.txt Normal file
View File

@@ -0,0 +1,112 @@
:mod:`atexit` --- Exit handlers
===============================
.. module:: atexit
:synopsis: Register and execute cleanup functions.
.. moduleauthor:: Skip Montanaro <skip@pobox.com>
.. sectionauthor:: Skip Montanaro <skip@pobox.com>
--------------
The :mod:`atexit` module defines functions to register and unregister 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.
.. versionchanged:: 3.7
When used with C-API subinterpreters, registered functions
are local to the interpreter they were registered in.
.. 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.
This function returns *func*, which makes it possible to use it as a
decorator.
.. function:: unregister(func)
Remove *func* from the list of functions to be run at interpreter
shutdown. After calling :func:`unregister`, *func* is guaranteed not to be
called when the interpreter shuts down, even if it was registered more than
once. :func:`unregister` silently does nothing if *func* was not previously
registered.
.. 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:
with open("counterfile") as infile:
_count = int(infile.read())
except FileNotFoundError:
_count = 0
def incrcounter(n):
global _count
_count = _count + n
def savecounter():
with open("counterfile", "w") as outfile:
outfile.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.

282
web/python-docs/_sources/library/audioop.rst.txt Normal file
View File

@@ -0,0 +1,282 @@
: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, 24
or 32 bits wide, stored in :term:`bytes-like objects <bytes-like object>`. All scalar items are
integers, unless specified otherwise.
.. versionchanged:: 3.4
Support for 24-bit samples was added.
All functions now accept any :term:`bytes-like object`.
String input now results in an immediate error.
.. 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``, ``3`` 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.
.. 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:: byteswap(fragment, width)
"Byteswap" all samples in a fragment and returns the modified fragment.
Converts big-endian samples to little-endian and vice versa.
.. versionadded:: 3.4
.. 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
bytes object. 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.
.. function:: lin2lin(fragment, width, newwidth)
Convert samples between 1-, 2-, 3- and 4-byte formats.
.. note::
In some audio formats, such as .WAV files, 16, 24 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, 24
or 32 bit width samples.
.. function:: lin2ulaw(fragment, width)
Convert samples in the audio fragment to u-LAW encoding and return this as a
bytes object. 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)

47
web/python-docs/_sources/library/audit_events.rst.txt Normal file
View File

@@ -0,0 +1,47 @@
.. _audit-events:
.. index:: single: audit events
Audit events table
==================
This table contains all events raised by :func:`sys.audit` or
:c:func:`PySys_Audit` calls throughout the CPython runtime and the
standard library. These calls were added in 3.8.0 or later (see :pep:`578`).
See :func:`sys.addaudithook` and :c:func:`PySys_AddAuditHook` for
information on handling these events.
.. impl-detail::
This table is generated from the CPython documentation, and may not
represent events raised by other implementations. See your runtime
specific documentation for actual events raised.
.. audit-event-table::
The following events are raised internally and do not correspond to any
public API of CPython:
+--------------------------+-------------------------------------------+
| Audit event | Arguments |
+==========================+===========================================+
| _winapi.CreateFile | ``file_name``, ``desired_access``, |
| | ``share_mode``, ``creation_disposition``, |
| | ``flags_and_attributes`` |
+--------------------------+-------------------------------------------+
| _winapi.CreateJunction | ``src_path``, ``dst_path`` |
+--------------------------+-------------------------------------------+
| _winapi.CreateNamedPipe | ``name``, ``open_mode``, ``pipe_mode`` |
+--------------------------+-------------------------------------------+
| _winapi.CreatePipe | |
+--------------------------+-------------------------------------------+
| _winapi.CreateProcess | ``application_name``, ``command_line``, |
| | ``current_directory`` |
+--------------------------+-------------------------------------------+
| _winapi.OpenProcess | ``process_id``, ``desired_access`` |
+--------------------------+-------------------------------------------+
| _winapi.TerminateProcess | ``handle``, ``exit_code`` |
+--------------------------+-------------------------------------------+
| ctypes.PyObj_FromPtr | ``obj`` |
+--------------------------+-------------------------------------------+

290
web/python-docs/_sources/library/base64.rst.txt Normal file
View File

@@ -0,0 +1,290 @@
:mod:`base64` --- Base16, Base32, Base64, Base85 Data Encodings
===============================================================
.. module:: base64
:synopsis: RFC 3548: Base16, Base32, Base64 Data Encodings;
Base85 and Ascii85
**Source code:** :source:`Lib/base64.py`
.. index::
pair: base64; encoding
single: MIME; base64 encoding
--------------
This module provides functions for encoding binary data to printable
ASCII characters and decoding such encodings back to binary data.
It provides encoding and decoding functions for the encodings specified in
:rfc:`3548`, which defines the Base16, Base32, and Base64 algorithms,
and for the de-facto standard Ascii85 and Base85 encodings.
The :rfc:`3548` encodings are suitable for encoding binary data so that it can
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 :term:`bytes-like objects <bytes-like object>` to ASCII
:class:`bytes`, and decoding :term:`bytes-like objects <bytes-like object>` or
strings containing ASCII to :class:`bytes`. Both base-64 alphabets
defined in :rfc:`3548` (normal, and URL- and filesystem-safe) are supported.
The legacy interface does not support decoding from strings, but it does
provide functions for encoding and decoding to and from :term:`file objects
<file object>`. It only supports the Base64 standard alphabet, and it adds
newlines every 76 characters as per :rfc:`2045`. Note that if you are looking
for :rfc:`2045` support you probably want to be looking at the :mod:`email`
package instead.
.. versionchanged:: 3.3
ASCII-only Unicode strings are now accepted by the decoding functions of
the modern interface.
.. versionchanged:: 3.4
Any :term:`bytes-like objects <bytes-like object>` are now accepted by all
encoding and decoding functions in this module. Ascii85/Base85 support added.
The modern interface provides:
.. function:: b64encode(s, altchars=None)
Encode the :term:`bytes-like object` *s* using Base64 and return the encoded
:class:`bytes`.
Optional *altchars* must be a :term:`bytes-like object` 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.
.. function:: b64decode(s, altchars=None, validate=False)
Decode the Base64 encoded :term:`bytes-like object` or ASCII string
*s* and return the decoded :class:`bytes`.
Optional *altchars* must be a :term:`bytes-like object` or ASCII string of
at least length 2 (additional characters are ignored) which specifies the
alternative alphabet used instead of the ``+`` and ``/`` characters.
A :exc:`binascii.Error` exception is raised
if *s* is incorrectly padded.
If *validate* is ``False`` (the default), characters that are neither
in the normal base-64 alphabet nor the alternative alphabet are
discarded prior to the padding check. If *validate* is ``True``,
these non-alphabet characters in the input result in a
:exc:`binascii.Error`.
.. function:: standard_b64encode(s)
Encode :term:`bytes-like object` *s* using the standard Base64 alphabet
and return the encoded :class:`bytes`.
.. function:: standard_b64decode(s)
Decode :term:`bytes-like object` or ASCII string *s* using the standard
Base64 alphabet and return the decoded :class:`bytes`.
.. function:: urlsafe_b64encode(s)
Encode :term:`bytes-like object` *s* using the
URL- and filesystem-safe alphabet, which
substitutes ``-`` instead of ``+`` and ``_`` instead of ``/`` in the
standard Base64 alphabet, and return the encoded :class:`bytes`. The result
can still contain ``=``.
.. function:: urlsafe_b64decode(s)
Decode :term:`bytes-like object` or ASCII string *s*
using the URL- and filesystem-safe
alphabet, which substitutes ``-`` instead of ``+`` and ``_`` instead of
``/`` in the standard Base64 alphabet, and return the decoded
:class:`bytes`.
.. function:: b32encode(s)
Encode the :term:`bytes-like object` *s* using Base32 and return the
encoded :class:`bytes`.
.. function:: b32decode(s, casefold=False, map01=None)
Decode the Base32 encoded :term:`bytes-like object` or ASCII string *s* and
return the decoded :class:`bytes`.
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.
A :exc:`binascii.Error` is raised if *s* is
incorrectly padded or if there are non-alphabet characters present in the
input.
.. function:: b16encode(s)
Encode the :term:`bytes-like object` *s* using Base16 and return the
encoded :class:`bytes`.
.. function:: b16decode(s, casefold=False)
Decode the Base16 encoded :term:`bytes-like object` or ASCII string *s* and
return the decoded :class:`bytes`.
Optional *casefold* is a flag specifying whether a
lowercase alphabet is acceptable as input. For security purposes, the default
is ``False``.
A :exc:`binascii.Error` is raised if *s* is
incorrectly padded or if there are non-alphabet characters present in the
input.
.. function:: a85encode(b, *, foldspaces=False, wrapcol=0, pad=False, adobe=False)
Encode the :term:`bytes-like object` *b* using Ascii85 and return the
encoded :class:`bytes`.
*foldspaces* is an optional flag that uses the special short sequence 'y'
instead of 4 consecutive spaces (ASCII 0x20) as supported by 'btoa'. This
feature is not supported by the "standard" Ascii85 encoding.
*wrapcol* controls whether the output should have newline (``b'\n'``)
characters added to it. If this is non-zero, each output line will be
at most this many characters long.
*pad* controls whether the input is padded to a multiple of 4
before encoding. Note that the ``btoa`` implementation always pads.
*adobe* controls whether the encoded byte sequence is framed with ``<~``
and ``~>``, which is used by the Adobe implementation.
.. versionadded:: 3.4
.. function:: a85decode(b, *, foldspaces=False, adobe=False, ignorechars=b' \\t\\n\\r\\v')
Decode the Ascii85 encoded :term:`bytes-like object` or ASCII string *b* and
return the decoded :class:`bytes`.
*foldspaces* is a flag that specifies whether the 'y' short sequence
should be accepted as shorthand for 4 consecutive spaces (ASCII 0x20).
This feature is not supported by the "standard" Ascii85 encoding.
*adobe* controls whether the input sequence is in Adobe Ascii85 format
(i.e. is framed with <~ and ~>).
*ignorechars* should be a :term:`bytes-like object` or ASCII string
containing characters to ignore
from the input. This should only contain whitespace characters, and by
default contains all whitespace characters in ASCII.
.. versionadded:: 3.4
.. function:: b85encode(b, pad=False)
Encode the :term:`bytes-like object` *b* using base85 (as used in e.g.
git-style binary diffs) and return the encoded :class:`bytes`.
If *pad* is true, the input is padded with ``b'\0'`` so its length is a
multiple of 4 bytes before encoding.
.. versionadded:: 3.4
.. function:: b85decode(b)
Decode the base85-encoded :term:`bytes-like object` or ASCII string *b* and
return the decoded :class:`bytes`. Padding is implicitly removed, if
necessary.
.. versionadded:: 3.4
The legacy interface:
.. function:: decode(input, output)
Decode the contents of the binary *input* file and write the resulting binary
data to the *output* file. *input* and *output* must be :term:`file objects
<file object>`. *input* will be read until ``input.readline()`` returns an
empty bytes object.
.. function:: decodebytes(s)
Decode the :term:`bytes-like object` *s*, which must contain one or more
lines of base64 encoded data, and return the decoded :class:`bytes`.
.. versionadded:: 3.1
.. function:: decodestring(s)
Deprecated alias of :func:`decodebytes`.
.. deprecated:: 3.1
.. function:: encode(input, output)
Encode the contents of the binary *input* file and write the resulting base64
encoded data to the *output* file. *input* and *output* must be :term:`file
objects <file object>`. *input* will be read until ``input.read()`` returns
an empty bytes object. :func:`encode` inserts a newline character (``b'\n'``)
after every 76 bytes of the output, as well as ensuring that the output
always ends with a newline, as per :rfc:`2045` (MIME).
.. function:: encodebytes(s)
Encode the :term:`bytes-like object` *s*, which can contain arbitrary binary
data, and return :class:`bytes` containing the base64-encoded data, with newlines
(``b'\n'``) inserted after every 76 bytes of output, and ensuring that
there is a trailing newline, as per :rfc:`2045` (MIME).
.. versionadded:: 3.1
.. function:: encodestring(s)
Deprecated alias of :func:`encodebytes`.
.. deprecated:: 3.1
An example usage of the module:
>>> import base64
>>> encoded = base64.b64encode(b'data to be encoded')
>>> encoded
b'ZGF0YSB0byBiZSBlbmNvZGVk'
>>> data = base64.b64decode(encoded)
>>> data
b'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.

372
web/python-docs/_sources/library/bdb.rst.txt Normal file
View File

@@ -0,0 +1,372 @@
: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:: bpformat()
Return a string with all the information about the breakpoint, nicely
formatted:
* 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.
.. versionadded:: 3.2
.. method:: bpprint(out=None)
Print the output of :meth:`bpformat` to the file *out*, or if it is
``None``, to standard output.
.. 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:: 3.1
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, funcname)
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_bpbynumber(arg)
Return a breakpoint specified by the given number. If *arg* is a string,
it will be converted to a number. If *arg* is a non-numeric string, if
the given breakpoint never existed or has been deleted, a
:exc:`ValueError` is raised.
.. versionadded:: 3.2
.. 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=None, locals=None)
Debug a statement executed via the :func:`exec` function. *globals*
defaults to :attr:`__main__.__dict__`, *locals* defaults to *globals*.
.. method:: runeval(expr, globals=None, locals=None)
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.

23
web/python-docs/_sources/library/binary.rst.txt Normal file
View File

@@ -0,0 +1,23 @@
.. _binaryservices:
********************
Binary Data Services
********************
The modules described in this chapter provide some basic services operations
for manipulation of binary data. Other operations on binary data, specifically
in relation to file formats and network protocols, are described in the
relevant sections.
Some libraries described under :ref:`textservices` also work with either
ASCII-compatible binary formats (for example, :mod:`re`) or all binary data
(for example, :mod:`difflib`).
In addition, see the documentation for Python's built-in binary data types in
:ref:`binaryseq`.
.. toctree::
struct.rst
codecs.rst

212
web/python-docs/_sources/library/binascii.rst.txt Normal file
View File

@@ -0,0 +1,212 @@
: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.
.. note::
``a2b_*`` functions accept Unicode strings containing only ASCII characters.
Other functions only accept :term:`bytes-like objects <bytes-like object>` (such as
:class:`bytes`, :class:`bytearray` and other objects that support the buffer
protocol).
.. versionchanged:: 3.3
ASCII-only unicode strings are now accepted by the ``a2b_*`` functions.
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, *, backtick=False)
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. If *backtick* is true, zeros are represented by ``'`'`` instead of spaces.
.. versionchanged:: 3.7
Added the *backtick* parameter.
.. 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, *, newline=True)
Convert binary data to a line of ASCII characters in base64 coding. The return
value is the converted line, including a newline char if *newline* is
true. The output of this function conforms to :rfc:`3548`.
.. versionchanged:: 3.6
Added the *newline* parameter.
.. function:: a2b_qp(data, header=False)
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=False, istext=True, header=False)
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 :rfc:`1522`. 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.
.. versionchanged:: 3.2
Accept only bytestring or bytearray objects as input.
.. 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, value)
Compute a 16-bit CRC value of *data*, starting with *value* as the
initial CRC, and return 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[, value])
Compute CRC-32, the 32-bit checksum of *data*, starting with an
initial CRC of *value*. The default initial CRC is zero. The algorithm
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(b"hello world"))
# Or, in two pieces:
crc = binascii.crc32(b"hello")
crc = binascii.crc32(b" world", crc)
print('crc32 = {:#010x}'.format(crc))
.. versionchanged:: 3.0
The result is always unsigned.
To generate the same numeric value across all Python versions and
platforms, use ``crc32(data) & 0xffffffff``.
.. function:: b2a_hex(data[, sep[, bytes_per_sep=1]])
hexlify(data[, sep[, bytes_per_sep=1]])
Return the hexadecimal representation of the binary *data*. Every byte of
*data* is converted into the corresponding 2-digit hex representation. The
returned bytes object is therefore twice as long as the length of *data*.
Similar functionality (but returning a text string) is also conveniently
accessible using the :meth:`bytes.hex` method.
If *sep* is specified, it must be a single character str or bytes object.
It will be inserted in the output after every *bytes_per_sep* input bytes.
Separator placement is counted from the right end of the output by default,
if you wish to count from the left, supply a negative *bytes_per_sep* value.
>>> import binascii
>>> binascii.b2a_hex(b'\xb9\x01\xef')
b'b901ef'
>>> binascii.hexlify(b'\xb9\x01\xef', '-')
b'b9-01-ef'
>>> binascii.b2a_hex(b'\xb9\x01\xef', b'_', 2)
b'b9_01ef'
>>> binascii.b2a_hex(b'\xb9\x01\xef', b' ', -2)
b'b901 ef'
.. versionchanged:: 3.8
The *sep* and *bytes_per_sep* parameters were added.
.. 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 an
:exc:`Error` exception is raised.
Similar functionality (accepting only text string arguments, but more
liberal towards whitespace) is also accessible using the
:meth:`bytes.fromhex` class method.
.. 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, 64,
and 85.
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.

57
web/python-docs/_sources/library/binhex.rst.txt Normal file
View File

@@ -0,0 +1,57 @@
:mod:`binhex` --- Encode and decode binhex4 files
=================================================
.. module:: binhex
:synopsis: Encode and decode files in binhex4 format.
**Source code:** :source:`Lib/binhex.py`
--------------
This module encodes and decodes files in binhex4 format, a format allowing
representation of Macintosh files in ASCII. Only the data fork is handled.
The :mod:`binhex` module defines the following functions:
.. function:: binhex(input, output)
Convert a binary file with filename *input* to binhex file *output*. The
*output* parameter can either be a filename or a file-like object (any object
supporting a :meth:`write` and :meth:`close` method).
.. function:: hexbin(input, output)
Decode a binhex file *input*. *input* may be a filename or a file-like object
supporting :meth:`read` and :meth:`close` methods. The resulting file is written
to a file named *output*, unless the argument is ``None`` 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).

149
web/python-docs/_sources/library/bisect.rst.txt Normal file
View File

@@ -0,0 +1,149 @@
: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>
**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)

42
web/python-docs/_sources/library/builtins.rst.txt Normal file
View File

@@ -0,0 +1,42 @@
:mod:`builtins` --- Built-in objects
====================================
.. module:: builtins
:synopsis: The module that provides the built-in namespace.
--------------
This module provides direct access to all 'built-in' identifiers of Python; for
example, ``builtins.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 builtins
def open(path):
f = builtins.open(path, 'r')
return UpperCaser(f)
class UpperCaser:
'''Wrapper around a file that converts output to upper-case.'''
def __init__(self, f):
self._f = f
def read(self, count=-1):
return self._f.read(count).upper()
# ...
As an implementation detail, most modules have the name ``__builtins__`` made
available as part of their globals. The value of ``__builtins__`` is normally
either this module or the value of this module's :attr:`~object.__dict__` attribute.
Since this is an implementation detail, it may not be used by alternate
implementations of Python.

322
web/python-docs/_sources/library/bz2.rst.txt Normal file
View File

@@ -0,0 +1,322 @@
:mod:`bz2` --- Support for :program:`bzip2` compression
=======================================================
.. module:: bz2
:synopsis: Interfaces for bzip2 compression and decompression.
.. moduleauthor:: Gustavo Niemeyer <niemeyer@conectiva.com>
.. moduleauthor:: Nadeem Vawda <nadeem.vawda@gmail.com>
.. sectionauthor:: Gustavo Niemeyer <niemeyer@conectiva.com>
.. sectionauthor:: Nadeem Vawda <nadeem.vawda@gmail.com>
**Source code:** :source:`Lib/bz2.py`
--------------
This module provides a comprehensive interface for compressing and
decompressing data using the bzip2 compression algorithm.
The :mod:`bz2` module contains:
* The :func:`.open` function and :class:`BZ2File` class for reading and
writing compressed files.
* The :class:`BZ2Compressor` and :class:`BZ2Decompressor` classes for
incremental (de)compression.
* The :func:`compress` and :func:`decompress` functions for one-shot
(de)compression.
All of the classes in this module may safely be accessed from multiple threads.
(De)compression of files
------------------------
.. function:: open(filename, mode='r', compresslevel=9, encoding=None, errors=None, newline=None)
Open a bzip2-compressed file in binary or text mode, returning a :term:`file
object`.
As with the constructor for :class:`BZ2File`, the *filename* argument can be
an actual filename (a :class:`str` or :class:`bytes` object), or an existing
file object to read from or write to.
The *mode* argument can be any of ``'r'``, ``'rb'``, ``'w'``, ``'wb'``,
``'x'``, ``'xb'``, ``'a'`` or ``'ab'`` for binary mode, or ``'rt'``,
``'wt'``, ``'xt'``, or ``'at'`` for text mode. The default is ``'rb'``.
The *compresslevel* argument is an integer from 1 to 9, as for the
:class:`BZ2File` constructor.
For binary mode, this function is equivalent to the :class:`BZ2File`
constructor: ``BZ2File(filename, mode, compresslevel=compresslevel)``. In
this case, the *encoding*, *errors* and *newline* arguments must not be
provided.
For text mode, a :class:`BZ2File` object is created, and wrapped in an
:class:`io.TextIOWrapper` instance with the specified encoding, error
handling behavior, and line ending(s).
.. versionadded:: 3.3
.. versionchanged:: 3.4
The ``'x'`` (exclusive creation) mode was added.
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
.. class:: BZ2File(filename, mode='r', buffering=None, compresslevel=9)
Open a bzip2-compressed file in binary mode.
If *filename* is a :class:`str` or :class:`bytes` object, open the named file
directly. Otherwise, *filename* should be a :term:`file object`, which will
be used to read or write the compressed data.
The *mode* argument can be either ``'r'`` for reading (default), ``'w'`` for
overwriting, ``'x'`` for exclusive creation, or ``'a'`` for appending. These
can equivalently be given as ``'rb'``, ``'wb'``, ``'xb'`` and ``'ab'``
respectively.
If *filename* is a file object (rather than an actual file name), a mode of
``'w'`` does not truncate the file, and is instead equivalent to ``'a'``.
The *buffering* argument is ignored. Its use is deprecated since Python 3.0.
If *mode* is ``'w'`` or ``'a'``, *compresslevel* can be an integer between
``1`` and ``9`` specifying the level of compression: ``1`` produces the
least compression, and ``9`` (default) produces the most compression.
If *mode* is ``'r'``, the input file may be the concatenation of multiple
compressed streams.
:class:`BZ2File` provides all of the members specified by the
:class:`io.BufferedIOBase`, except for :meth:`detach` and :meth:`truncate`.
Iteration and the :keyword:`with` statement are supported.
:class:`BZ2File` also provides the following method:
.. method:: peek([n])
Return buffered data without advancing the file position. At least one
byte of data will be returned (unless at EOF). The exact number of bytes
returned is unspecified.
.. note:: While calling :meth:`peek` does not change the file position of
the :class:`BZ2File`, it may change the position of the underlying file
object (e.g. if the :class:`BZ2File` was constructed by passing a file
object for *filename*).
.. versionadded:: 3.3
.. deprecated:: 3.0
The keyword argument *buffering* was deprecated and is now ignored.
.. versionchanged:: 3.1
Support for the :keyword:`with` statement was added.
.. versionchanged:: 3.3
The :meth:`fileno`, :meth:`readable`, :meth:`seekable`, :meth:`writable`,
:meth:`read1` and :meth:`readinto` methods were added.
.. versionchanged:: 3.3
Support was added for *filename* being a :term:`file object` instead of an
actual filename.
.. versionchanged:: 3.3
The ``'a'`` (append) mode was added, along with support for reading
multi-stream files.
.. versionchanged:: 3.4
The ``'x'`` (exclusive creation) mode was added.
.. versionchanged:: 3.5
The :meth:`~io.BufferedIOBase.read` method now accepts an argument of
``None``.
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
Incremental (de)compression
---------------------------
.. class:: BZ2Compressor(compresslevel=9)
Create a new compressor object. This object may be used to compress data
incrementally. For one-shot compression, use the :func:`compress` function
instead.
*compresslevel*, if given, must be an integer between ``1`` and ``9``. The
default is ``9``.
.. method:: compress(data)
Provide data to the compressor object. Returns a chunk of compressed data
if possible, or an empty byte string otherwise.
When you have finished providing data to the compressor, call the
:meth:`flush` method to finish the compression process.
.. method:: flush()
Finish the compression process. Returns the compressed data left in
internal buffers.
The compressor object may not be used after this method has been called.
.. class:: BZ2Decompressor()
Create a new decompressor object. This object may be used to decompress data
incrementally. For one-shot compression, use the :func:`decompress` function
instead.
.. note::
This class does not transparently handle inputs containing multiple
compressed streams, unlike :func:`decompress` and :class:`BZ2File`. If
you need to decompress a multi-stream input with :class:`BZ2Decompressor`,
you must use a new decompressor for each stream.
.. method:: decompress(data, max_length=-1)
Decompress *data* (a :term:`bytes-like object`), returning
uncompressed data as bytes. Some of *data* may be buffered
internally, for use in later calls to :meth:`decompress`. The
returned data should be concatenated with the output of any
previous calls to :meth:`decompress`.
If *max_length* is nonnegative, returns at most *max_length*
bytes of decompressed data. If this limit is reached and further
output can be produced, the :attr:`~.needs_input` attribute will
be set to ``False``. In this case, the next call to
:meth:`~.decompress` may provide *data* as ``b''`` to obtain
more of the output.
If all of the input data was decompressed and returned (either
because this was less than *max_length* bytes, or because
*max_length* was negative), the :attr:`~.needs_input` attribute
will be set to ``True``.
Attempting to decompress data after the end of stream is reached
raises an `EOFError`. Any data found after the end of the
stream is ignored and saved in the :attr:`~.unused_data` attribute.
.. versionchanged:: 3.5
Added the *max_length* parameter.
.. attribute:: eof
``True`` if the end-of-stream marker has been reached.
.. versionadded:: 3.3
.. attribute:: unused_data
Data found after the end of the compressed stream.
If this attribute is accessed before the end of the stream has been
reached, its value will be ``b''``.
.. attribute:: needs_input
``False`` if the :meth:`.decompress` method can provide more
decompressed data before requiring new uncompressed input.
.. versionadded:: 3.5
One-shot (de)compression
------------------------
.. function:: compress(data, compresslevel=9)
Compress *data*, a :term:`bytes-like object <bytes-like object>`.
*compresslevel*, if given, must be an integer between ``1`` and ``9``. The
default is ``9``.
For incremental compression, use a :class:`BZ2Compressor` instead.
.. function:: decompress(data)
Decompress *data*, a :term:`bytes-like object <bytes-like object>`.
If *data* is the concatenation of multiple compressed streams, decompress
all of the streams.
For incremental decompression, use a :class:`BZ2Decompressor` instead.
.. versionchanged:: 3.3
Support for multi-stream inputs was added.
.. _bz2-usage-examples:
Examples of usage
-----------------
Below are some examples of typical usage of the :mod:`bz2` module.
Using :func:`compress` and :func:`decompress` to demonstrate round-trip compression:
>>> import bz2
>>> data = b"""\
... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
... sit amet cursus ante. In interdum laoreet mi, sit amet ultrices purus
... pulvinar a. Nam gravida euismod magna, non varius justo tincidunt feugiat.
... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
>>> c = bz2.compress(data)
>>> len(data) / len(c) # Data compression ratio
1.513595166163142
>>> d = bz2.decompress(c)
>>> data == d # Check equality to original object after round-trip
True
Using :class:`BZ2Compressor` for incremental compression:
>>> import bz2
>>> def gen_data(chunks=10, chunksize=1000):
... """Yield incremental blocks of chunksize bytes."""
... for _ in range(chunks):
... yield b"z" * chunksize
...
>>> comp = bz2.BZ2Compressor()
>>> out = b""
>>> for chunk in gen_data():
... # Provide data to the compressor object
... out = out + comp.compress(chunk)
...
>>> # Finish the compression process. Call this once you have
>>> # finished providing data to the compressor.
>>> out = out + comp.flush()
The example above uses a very "nonrandom" stream of data
(a stream of `b"z"` chunks). Random data tends to compress poorly,
while ordered, repetitive data usually yields a high compression ratio.
Writing and reading a bzip2-compressed file in binary mode:
>>> import bz2
>>> data = b"""\
... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
... sit amet cursus ante. In interdum laoreet mi, sit amet ultrices purus
... pulvinar a. Nam gravida euismod magna, non varius justo tincidunt feugiat.
... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
>>> with bz2.open("myfile.bz2", "wb") as f:
... # Write compressed data to file
... unused = f.write(data)
>>> with bz2.open("myfile.bz2", "rb") as f:
... # Decompress data from file
... content = f.read()
>>> content == data # Check equality to original object after round-trip
True

420
web/python-docs/_sources/library/calendar.rst.txt Normal file
View File

@@ -0,0 +1,420 @@
: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.
The functions and classes defined in this module
use an idealized calendar, the current Gregorian calendar extended indefinitely
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. Zero and negative years are
interpreted as prescribed by the ISO 8601 standard. Year 0 is 1 BC, year -1 is
2 BC, and so on.
.. class:: Calendar(firstweekday=0)
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.
: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:: itermonthdays(year, month)
Return an iterator for the month *month* in the year *year* similar to
:meth:`itermonthdates`, but not restricted by the :class:`datetime.date`
range. Days returned will simply be day of the month numbers. For the
days outside of the specified month, the day number is ``0``.
.. method:: itermonthdays2(year, month)
Return an iterator for the month *month* in the year *year* similar to
:meth:`itermonthdates`, but not restricted by the :class:`datetime.date`
range. Days returned will be tuples consisting of a day of the month
number and a week day number.
.. method:: itermonthdays3(year, month)
Return an iterator for the month *month* in the year *year* similar to
:meth:`itermonthdates`, but not restricted by the :class:`datetime.date`
range. Days returned will be tuples consisting of a year, a month and a day
of the month numbers.
.. versionadded:: 3.7
.. method:: itermonthdays4(year, month)
Return an iterator for the month *month* in the year *year* similar to
:meth:`itermonthdates`, but not restricted by the :class:`datetime.date`
range. Days returned will be tuples consisting of a year, a month, a day
of the month, and a day of the week numbers.
.. versionadded:: 3.7
.. 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=3)
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=3)
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=3)
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=0)
This class can be used to generate plain text calendars.
:class:`TextCalendar` instances have the following methods:
.. method:: formatmonth(theyear, themonth, w=0, l=0)
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=0, l=0)
Print a month's calendar as returned by :meth:`formatmonth`.
.. method:: formatyear(theyear, w=2, l=1, c=6, m=3)
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=2, l=1, c=6, m=3)
Print the calendar for an entire year as returned by :meth:`formatyear`.
.. class:: HTMLCalendar(firstweekday=0)
This class can be used to generate HTML calendars.
:class:`!HTMLCalendar` instances have the following methods:
.. method:: formatmonth(theyear, themonth, withyear=True)
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=3)
Return a year's calendar as an HTML table. *width* (defaulting to 3)
specifies the number of months per row.
.. method:: formatyearpage(theyear, width=3, css='calendar.css', encoding=None)
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:`!HTMLCalendar` has the following attributes you can override to
customize the CSS classes used by the calendar:
.. attribute:: cssclasses
A list of CSS classes used for each weekday. The default class list is::
cssclasses = ["mon", "tue", "wed", "thu", "fri", "sat", "sun"]
more styles can be added for each day::
cssclasses = ["mon text-bold", "tue", "wed", "thu", "fri", "sat", "sun red"]
Note that the length of this list must be seven items.
.. attribute:: cssclass_noday
The CSS class for a weekday occurring in the previous or coming month.
.. versionadded:: 3.7
.. attribute:: cssclasses_weekday_head
A list of CSS classes used for weekday names in the header row.
The default is the same as :attr:`cssclasses`.
.. versionadded:: 3.7
.. attribute:: cssclass_month_head
The month's head CSS class (used by :meth:`formatmonthname`).
The default value is ``"month"``.
.. versionadded:: 3.7
.. attribute:: cssclass_month
The CSS class for the whole month's table (used by :meth:`formatmonth`).
The default value is ``"month"``.
.. versionadded:: 3.7
.. attribute:: cssclass_year
The CSS class for the whole year's table of tables (used by
:meth:`formatyear`). The default value is ``"year"``.
.. versionadded:: 3.7
.. attribute:: cssclass_year_head
The CSS class for the table head for the whole year (used by
:meth:`formatyear`). The default value is ``"year"``.
.. versionadded:: 3.7
Note that although the naming for the above described class attributes is
singular (e.g. ``cssclass_month`` ``cssclass_noday``), one can replace the
single CSS class with a space separated list of CSS classes, for example::
"text-bold text-red"
Here is an example how :class:`!HTMLCalendar` can be customized::
class CustomHTMLCal(calendar.HTMLCalendar):
cssclasses = [style + " text-nowrap" for style in
calendar.HTMLCalendar.cssclasses]
cssclass_month_head = "text-center month-head"
cssclass_month = "text-center month"
cssclass_year = "text-italic lead"
.. class:: LocaleTextCalendar(firstweekday=0, locale=None)
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.
.. class:: LocaleHTMLCalendar(firstweekday=0, locale=None)
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.
.. 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)
.. function:: firstweekday()
Returns the current setting for the weekday to start each week.
.. 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.
This function works for ranges spanning a century change.
.. 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 are represented by zeros. Each week begins with Monday
unless set by :func:`setfirstweekday`.
.. function:: prmonth(theyear, themonth, w=0, l=0)
Prints a month's calendar as returned by :func:`month`.
.. function:: month(theyear, themonth, w=0, l=0)
Returns a month's calendar in a multi-line string using the :meth:`formatmonth`
of the :class:`TextCalendar` class.
.. function:: prcal(year, w=0, l=0, c=6, m=3)
Prints the calendar for an entire year as returned by :func:`calendar`.
.. function:: calendar(year, w=2, l=1, c=6, m=3)
Returns a 3-column calendar for an entire year as a multi-line string using
the :meth:`formatyear` of the :class:`TextCalendar` class.
.. 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.
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.

524
web/python-docs/_sources/library/cgi.rst.txt Normal file
View File

@@ -0,0 +1,524 @@
:mod:`cgi` --- Common Gateway Interface support
===============================================
.. module:: cgi
:synopsis: Helpers for running Python scripts via the Common Gateway Interface.
**Source code:** :source:`Lib/cgi.py`
.. index::
pair: WWW; server
pair: CGI; protocol
pair: HTTP; protocol
pair: MIME; headers
single: URL
single: Common Gateway Interface
--------------
Support module for Common Gateway Interface (CGI) scripts.
This module defines a number of utilities for use by CGI scripts written in
Python.
Introduction
------------
.. _cgi-intro:
A CGI script is invoked by an HTTP server, usually to process user input
submitted through an HTML ``<FORM>`` or ``<ISINDEX>`` element.
Most often, CGI scripts live in the server's special :file:`cgi-bin` directory.
The HTTP server places all sorts of information about the request (such as the
client's hostname, the requested URL, the query string, and lots of other
goodies) in the script's shell environment, executes the script, and sends the
script's output back to the client.
The script's input is connected to the client too, and sometimes the form data
is read this way; at other times the form data is passed via the "query string"
part of the URL. This module is intended to take care of the different cases
and provide a simpler interface to the Python script. It also provides a number
of utilities that help in debugging scripts, and the latest addition is support
for file uploads from a form (if your browser supports it).
The output of a CGI script should consist of two sections, separated by a blank
line. The first section contains a number of headers, telling the client what
kind of data is following. Python code to generate a minimal header section
looks like this::
print("Content-Type: text/html") # HTML is following
print() # blank line, end of headers
The second section is usually HTML, which allows the client software to display
nicely formatted text with header, in-line images, etc. Here's Python code that
prints a simple piece of HTML::
print("<TITLE>CGI script output</TITLE>")
print("<H1>This is my first CGI script</H1>")
print("Hello, world!")
.. _using-the-cgi-module:
Using the cgi module
--------------------
Begin by writing ``import cgi``.
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, use the :class:`FieldStorage` class. If the form
contains non-ASCII characters, use the *encoding* keyword parameter set to the
value of the encoding defined for the document. It is usually contained in the
META tag in the HEAD section of the HTML document or by the
:mailheader:`Content-Type` header). This reads the form contents from the
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 :meth:`~FieldStorage.getvalue`
method reads the entire file in memory as bytes. 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 from the :attr:`!file`
attribute before it is automatically closed as part of the garbage collection of
the :class:`FieldStorage` instance
(the :func:`~io.RawIOBase.read` and :func:`~io.IOBase.readline` methods will
return bytes)::
fileitem = form["userfile"]
if fileitem.file:
# It's an uploaded file; count lines
linecount = 0
while True:
line = fileitem.file.readline()
if not line: break
linecount = linecount + 1
:class:`FieldStorage` objects also support being used in a :keyword:`with`
statement, which will automatically close them when done.
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.
.. versionchanged:: 3.4
The :attr:`~FieldStorage.file` attribute is automatically closed upon the
garbage collection of the creating :class:`FieldStorage` instance.
.. versionchanged:: 3.5
Added support for the context management protocol to the
:class:`FieldStorage` class.
Higher Level Interface
----------------------
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=None)
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)
.. _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=None, environ=os.environ, keep_blank_values=False, strict_parsing=False, separator="&")
Parse a query in the environment or from a file (the file defaults to
``sys.stdin``). The *keep_blank_values*, *strict_parsing* and *separator* parameters are
passed to :func:`urllib.parse.parse_qs` unchanged.
.. versionchanged:: 3.8.8
Added the *separator* parameter.
.. function:: parse_multipart(fp, pdict, encoding="utf-8", errors="replace", separator="&")
Parse input of type :mimetype:`multipart/form-data` (for file uploads).
Arguments are *fp* for the input file, *pdict* for a dictionary containing
other parameters in the :mailheader:`Content-Type` header, and *encoding*,
the request encoding.
Returns a dictionary just like :func:`urllib.parse.parse_qs`: keys are the
field names, each value is a list of values for that field. For non-file
fields, the value is a list of strings.
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.
.. versionchanged:: 3.7
Added the *encoding* and *errors* parameters. For non-file fields, the
value is now a list of strings, not bytes.
.. versionchanged:: 3.8.8
Added the *separator* parameter.
.. 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.
.. _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 ``0o755`` 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 ``0o644`` for
readable and ``0o666`` 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.

84
web/python-docs/_sources/library/cgitb.rst.txt Normal file
View File

@@ -0,0 +1,84 @@
: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>
**Source code:** :source:`Lib/cgitb.py`
.. 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=1, logdir=None, context=5, format="html")
.. 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:: text(info, context=5)
This function handles the exception described by *info* (a 3-tuple containing
the result of :func:`sys.exc_info`), formatting its traceback as text and
returning the result as a string. 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``.
.. function:: html(info, context=5)
This function handles the exception described by *info* (a 3-tuple containing
the result of :func:`sys.exc_info`), formatting its traceback as HTML and
returning the result as a string. 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``.
.. function:: handler(info=None)
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`.

137
web/python-docs/_sources/library/chunk.rst.txt Normal file
View File

@@ -0,0 +1,137 @@
: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>
**Source code:** :source:`Lib/chunk.py`
.. 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=True, bigendian=True, inclheader=False)
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:`~io.IOBase.read`. If the methods
:meth:`~io.IOBase.seek` and :meth:`~io.IOBase.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:`OSError` if called after the
:meth:`close` method has been called. Before Python 3.3, they used to
raise :exc:`IOError`, now an alias of :exc:`OSError`.
.. method:: isatty()
Returns ``False``.
.. method:: seek(pos, whence=0)
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=-1)
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. An empty
bytes object 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 ``b''``. 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.

316
web/python-docs/_sources/library/cmath.rst.txt Normal file
View File

@@ -0,0 +1,316 @@
:mod:`cmath` --- Mathematical functions for complex numbers
===========================================================
.. module:: cmath
:synopsis: Mathematical functions for complex numbers.
--------------
This module 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.141592653589793
>>> phase(complex(-1.0, -0.0))
-3.141592653589793
.. 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))``.
.. 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)``.
Power and logarithmic functions
-------------------------------
.. function:: exp(x)
Return *e* raised to the power *x*, where *e* is the base of natural
logarithms.
.. 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.
.. 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.
.. 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.
.. 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.
.. 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:: isfinite(x)
Return ``True`` if both the real and imaginary parts of *x* are finite, and
``False`` otherwise.
.. versionadded:: 3.2
.. function:: isinf(x)
Return ``True`` if either the real or the imaginary part of *x* is an
infinity, and ``False`` otherwise.
.. function:: isnan(x)
Return ``True`` if either the real or the imaginary part of *x* is a NaN,
and ``False`` otherwise.
.. function:: isclose(a, b, *, rel_tol=1e-09, abs_tol=0.0)
Return ``True`` if the values *a* and *b* are close to each other and
``False`` otherwise.
Whether or not two values are considered close is determined according to
given absolute and relative tolerances.
*rel_tol* is the relative tolerance -- it is the maximum allowed difference
between *a* and *b*, relative to the larger absolute value of *a* or *b*.
For example, to set a tolerance of 5%, pass ``rel_tol=0.05``. The default
tolerance is ``1e-09``, which assures that the two values are the same
within about 9 decimal digits. *rel_tol* must be greater than zero.
*abs_tol* is the minimum absolute tolerance -- useful for comparisons near
zero. *abs_tol* must be at least zero.
If no errors occur, the result will be:
``abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)``.
The IEEE 754 special values of ``NaN``, ``inf``, and ``-inf`` will be
handled according to IEEE rules. Specifically, ``NaN`` is not considered
close to any other value, including ``NaN``. ``inf`` and ``-inf`` are only
considered close to themselves.
.. versionadded:: 3.5
.. seealso::
:pep:`485` -- A function for testing approximate equality
Constants
---------
.. data:: pi
The mathematical constant *π*, as a float.
.. data:: e
The mathematical constant *e*, as a float.
.. data:: tau
The mathematical constant *τ*, as a float.
.. versionadded:: 3.6
.. data:: inf
Floating-point positive infinity. Equivalent to ``float('inf')``.
.. versionadded:: 3.6
.. data:: infj
Complex number with zero real part and positive infinity imaginary
part. Equivalent to ``complex(0.0, float('inf'))``.
.. versionadded:: 3.6
.. data:: nan
A floating-point "not a number" (NaN) value. Equivalent to
``float('nan')``.
.. versionadded:: 3.6
.. data:: nanj
Complex number with zero real part and NaN imaginary part. Equivalent to
``complex(0.0, float('nan'))``.
.. versionadded:: 3.6
.. 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.

381
web/python-docs/_sources/library/cmd.rst.txt Normal file
View File

@@ -0,0 +1,381 @@
: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='tab', stdin=None, stdout=None)
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.
.. _cmd-objects:
Cmd Objects
-----------
A :class:`Cmd` instance has the following methods:
.. method:: Cmd.cmdloop(intro=None)
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'``.
.. index::
single: ? (question mark); in a command interpreter
single: ! (exclamation); in a command interpreter
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:`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.)
.. _cmd-example:
Cmd Example
-----------
.. sectionauthor:: Raymond Hettinger <python at rcn dot com>
The :mod:`cmd` module is mainly useful for building custom shells that let a
user work with a program interactively.
This section presents a simple example of how to build a shell around a few of
the commands in the :mod:`turtle` module.
Basic turtle commands such as :meth:`~turtle.forward` are added to a
:class:`Cmd` subclass with method named :meth:`do_forward`. The argument is
converted to a number and dispatched to the turtle module. The docstring is
used in the help utility provided by the shell.
The example also includes a basic record and playback facility implemented with
the :meth:`~Cmd.precmd` method which is responsible for converting the input to
lowercase and writing the commands to a file. The :meth:`do_playback` method
reads the file and adds the recorded commands to the :attr:`cmdqueue` for
immediate playback::
import cmd, sys
from turtle import *
class TurtleShell(cmd.Cmd):
intro = 'Welcome to the turtle shell. Type help or ? to list commands.\n'
prompt = '(turtle) '
file = None
# ----- basic turtle commands -----
def do_forward(self, arg):
'Move the turtle forward by the specified distance: FORWARD 10'
forward(*parse(arg))
def do_right(self, arg):
'Turn turtle right by given number of degrees: RIGHT 20'
right(*parse(arg))
def do_left(self, arg):
'Turn turtle left by given number of degrees: LEFT 90'
left(*parse(arg))
def do_goto(self, arg):
'Move turtle to an absolute position with changing orientation. GOTO 100 200'
goto(*parse(arg))
def do_home(self, arg):
'Return turtle to the home position: HOME'
home()
def do_circle(self, arg):
'Draw circle with given radius an options extent and steps: CIRCLE 50'
circle(*parse(arg))
def do_position(self, arg):
'Print the current turtle position: POSITION'
print('Current position is %d %d\n' % position())
def do_heading(self, arg):
'Print the current turtle heading in degrees: HEADING'
print('Current heading is %d\n' % (heading(),))
def do_color(self, arg):
'Set the color: COLOR BLUE'
color(arg.lower())
def do_undo(self, arg):
'Undo (repeatedly) the last turtle action(s): UNDO'
def do_reset(self, arg):
'Clear the screen and return turtle to center: RESET'
reset()
def do_bye(self, arg):
'Stop recording, close the turtle window, and exit: BYE'
print('Thank you for using Turtle')
self.close()
bye()
return True
# ----- record and playback -----
def do_record(self, arg):
'Save future commands to filename: RECORD rose.cmd'
self.file = open(arg, 'w')
def do_playback(self, arg):
'Playback commands from a file: PLAYBACK rose.cmd'
self.close()
with open(arg) as f:
self.cmdqueue.extend(f.read().splitlines())
def precmd(self, line):
line = line.lower()
if self.file and 'playback' not in line:
print(line, file=self.file)
return line
def close(self):
if self.file:
self.file.close()
self.file = None
def parse(arg):
'Convert a series of zero or more numbers to an argument tuple'
return tuple(map(int, arg.split()))
if __name__ == '__main__':
TurtleShell().cmdloop()
Here is a sample session with the turtle shell showing the help functions, using
blank lines to repeat commands, and the simple record and playback facility:
.. code-block:: none
Welcome to the turtle shell. Type help or ? to list commands.
(turtle) ?
Documented commands (type help <topic>):
========================================
bye color goto home playback record right
circle forward heading left position reset undo
(turtle) help forward
Move the turtle forward by the specified distance: FORWARD 10
(turtle) record spiral.cmd
(turtle) position
Current position is 0 0
(turtle) heading
Current heading is 0
(turtle) reset
(turtle) circle 20
(turtle) right 30
(turtle) circle 40
(turtle) right 30
(turtle) circle 60
(turtle) right 30
(turtle) circle 80
(turtle) right 30
(turtle) circle 100
(turtle) right 30
(turtle) circle 120
(turtle) right 30
(turtle) circle 120
(turtle) heading
Current heading is 180
(turtle) forward 100
(turtle)
(turtle) right 90
(turtle) forward 100
(turtle)
(turtle) right 90
(turtle) forward 400
(turtle) right 90
(turtle) forward 500
(turtle) right 90
(turtle) forward 400
(turtle) right 90
(turtle) forward 300
(turtle) playback spiral.cmd
Current position is 0 0
Current heading is 0
Current heading is 180
(turtle) bye
Thank you for using Turtle

184
web/python-docs/_sources/library/code.rst.txt Normal file
View File

@@ -0,0 +1,184 @@
:mod:`code` --- Interpreter base classes
========================================
.. module:: code
:synopsis: Facilities to implement read-eval-print loops.
**Source code:** :source:`Lib/code.py`
--------------
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=None)
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=None, filename="<console>")
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=None, readfunc=None, local=None, exitmsg=None)
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* and *exitmsg* passed as the
banner and exit message to use, if provided. The console object is discarded
after use.
.. versionchanged:: 3.6
Added *exitmsg* parameter.
.. function:: compile_command(source, filename="<input>", symbol="single")
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 ``'single'`` (the default), ``'eval'``
or ``'exec'``.
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="<input>", symbol="single")
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 of 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=None)
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.
.. versionchanged:: 3.5 The full chained traceback is displayed instead
of just the primary traceback.
.. 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=None, exitmsg=None)
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!).
The optional *exitmsg* argument specifies an exit message printed when exiting.
Pass the empty string to suppress the exit message. If *exitmsg* is not given or
``None``, a default message is printed.
.. versionchanged:: 3.4
To suppress printing any banner, pass an empty string.
.. versionchanged:: 3.6
Print an exit message when exiting.
.. method:: InteractiveConsole.push(line)
Push a line of source text to the interpreter. The line should not have a
trailing newline; it may have internal newlines. The line is appended to a
buffer and the interpreter's :meth:`runsource` method is called with the
concatenated contents of the buffer as source. If this indicates that the
command was executed or invalid, the buffer is reset; otherwise, the command is
incomplete, and the buffer is left as it was after the line was appended. The
return value is ``True`` if more input is required, ``False`` if the line was
dealt with in some way (this is the same as :meth:`runsource`).
.. method:: InteractiveConsole.resetbuffer()
Remove any unhandled source text from the input buffer.
.. method:: InteractiveConsole.raw_input(prompt="")
Write a prompt and read a line. The returned line does not include the trailing
newline. When the user enters the EOF key sequence, :exc:`EOFError` is raised.
The base implementation reads from ``sys.stdin``; a subclass may replace this
with a different implementation.

1498
web/python-docs/_sources/library/codecs.rst.txt Normal file
View File

File diff suppressed because it is too large Load Diff

73
web/python-docs/_sources/library/codeop.rst.txt Normal file
View File

@@ -0,0 +1,73 @@
: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>
**Source code:** :source:`Lib/codeop.py`
--------------
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="<input>", symbol="single")
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), as a sequence of statements (``'exec'``) 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.

314
web/python-docs/_sources/library/collections.abc.rst.txt Normal file
View File

@@ -0,0 +1,314 @@
:mod:`collections.abc` --- Abstract Base Classes for Containers
===============================================================
.. module:: collections.abc
:synopsis: Abstract base classes for containers
.. moduleauthor:: Raymond Hettinger <python at rcn.com>
.. sectionauthor:: Raymond Hettinger <python at rcn.com>
.. versionadded:: 3.3
Formerly, this module was part of the :mod:`collections` module.
**Source code:** :source:`Lib/_collections_abc.py`
.. testsetup:: *
from collections import *
import itertools
__name__ = '<doctest>'
--------------
This module provides :term:`abstract base classes <abstract base class>` that
can be used to test whether a class provides a particular interface; for
example, whether it is hashable or whether it is a mapping.
.. _collections-abstract-base-classes:
Collections Abstract Base Classes
---------------------------------
The collections module offers the following :term:`ABCs <abstract base class>`:
.. tabularcolumns:: |l|L|L|L|
========================== ====================== ======================= ====================================================
ABC Inherits from Abstract Methods Mixin Methods
========================== ====================== ======================= ====================================================
:class:`Container` ``__contains__``
:class:`Hashable` ``__hash__``
:class:`Iterable` ``__iter__``
:class:`Iterator` :class:`Iterable` ``__next__`` ``__iter__``
:class:`Reversible` :class:`Iterable` ``__reversed__``
:class:`Generator` :class:`Iterator` ``send``, ``throw`` ``close``, ``__iter__``, ``__next__``
:class:`Sized` ``__len__``
:class:`Callable` ``__call__``
:class:`Collection` :class:`Sized`, ``__contains__``,
:class:`Iterable`, ``__iter__``,
:class:`Container` ``__len__``
:class:`Sequence` :class:`Reversible`, ``__getitem__``, ``__contains__``, ``__iter__``, ``__reversed__``,
:class:`Collection` ``__len__`` ``index``, and ``count``
:class:`MutableSequence` :class:`Sequence` ``__getitem__``, Inherited :class:`Sequence` methods and
``__setitem__``, ``append``, ``reverse``, ``extend``, ``pop``,
``__delitem__``, ``remove``, and ``__iadd__``
``__len__``,
``insert``
:class:`ByteString` :class:`Sequence` ``__getitem__``, Inherited :class:`Sequence` methods
``__len__``
:class:`Set` :class:`Collection` ``__contains__``, ``__le__``, ``__lt__``, ``__eq__``, ``__ne__``,
``__iter__``, ``__gt__``, ``__ge__``, ``__and__``, ``__or__``,
``__len__`` ``__sub__``, ``__xor__``, and ``isdisjoint``
:class:`MutableSet` :class:`Set` ``__contains__``, Inherited :class:`Set` methods and
``__iter__``, ``clear``, ``pop``, ``remove``, ``__ior__``,
``__len__``, ``__iand__``, ``__ixor__``, and ``__isub__``
``add``,
``discard``
:class:`Mapping` :class:`Collection` ``__getitem__``, ``__contains__``, ``keys``, ``items``, ``values``,
``__iter__``, ``get``, ``__eq__``, and ``__ne__``
``__len__``
:class:`MutableMapping` :class:`Mapping` ``__getitem__``, Inherited :class:`Mapping` methods and
``__setitem__``, ``pop``, ``popitem``, ``clear``, ``update``,
``__delitem__``, and ``setdefault``
``__iter__``,
``__len__``
:class:`MappingView` :class:`Sized` ``__len__``
:class:`ItemsView` :class:`MappingView`, ``__contains__``,
:class:`Set` ``__iter__``
:class:`KeysView` :class:`MappingView`, ``__contains__``,
:class:`Set` ``__iter__``
:class:`ValuesView` :class:`MappingView`, ``__contains__``, ``__iter__``
:class:`Collection`
:class:`Awaitable` ``__await__``
:class:`Coroutine` :class:`Awaitable` ``send``, ``throw`` ``close``
:class:`AsyncIterable` ``__aiter__``
:class:`AsyncIterator` :class:`AsyncIterable` ``__anext__`` ``__aiter__``
:class:`AsyncGenerator` :class:`AsyncIterator` ``asend``, ``athrow`` ``aclose``, ``__aiter__``, ``__anext__``
========================== ====================== ======================= ====================================================
.. class:: Container
ABC for classes that provide the :meth:`__contains__` method.
.. class:: Hashable
ABC for classes that provide the :meth:`__hash__` method.
.. class:: Sized
ABC for classes that provide the :meth:`__len__` method.
.. class:: Callable
ABC for classes that provide the :meth:`__call__` method.
.. class:: Iterable
ABC for classes that provide the :meth:`__iter__` method.
Checking ``isinstance(obj, Iterable)`` detects classes that are registered
as :class:`Iterable` or that have an :meth:`__iter__` method, but it does
not detect classes that iterate with the :meth:`__getitem__` method.
The only reliable way to determine whether an object is :term:`iterable`
is to call ``iter(obj)``.
.. class:: Collection
ABC for sized iterable container classes.
.. versionadded:: 3.6
.. class:: Iterator
ABC for classes that provide the :meth:`~iterator.__iter__` and
:meth:`~iterator.__next__` methods. See also the definition of
:term:`iterator`.
.. class:: Reversible
ABC for iterable classes that also provide the :meth:`__reversed__`
method.
.. versionadded:: 3.6
.. class:: Generator
ABC for generator classes that implement the protocol defined in
:pep:`342` that extends iterators with the :meth:`~generator.send`,
:meth:`~generator.throw` and :meth:`~generator.close` methods.
See also the definition of :term:`generator`.
.. versionadded:: 3.5
.. class:: Sequence
MutableSequence
ByteString
ABCs for read-only and mutable :term:`sequences <sequence>`.
Implementation note: Some of the mixin methods, such as
:meth:`__iter__`, :meth:`__reversed__` and :meth:`index`, make
repeated calls to the underlying :meth:`__getitem__` method.
Consequently, if :meth:`__getitem__` is implemented with constant
access speed, the mixin methods will have linear performance;
however, if the underlying method is linear (as it would be with a
linked list), the mixins will have quadratic performance and will
likely need to be overridden.
.. versionchanged:: 3.5
The index() method added support for *stop* and *start*
arguments.
.. class:: Set
MutableSet
ABCs for read-only and mutable sets.
.. class:: Mapping
MutableMapping
ABCs for read-only and mutable :term:`mappings <mapping>`.
.. class:: MappingView
ItemsView
KeysView
ValuesView
ABCs for mapping, items, keys, and values :term:`views <dictionary view>`.
.. class:: Awaitable
ABC for :term:`awaitable` objects, which can be used in :keyword:`await`
expressions. Custom implementations must provide the :meth:`__await__`
method.
:term:`Coroutine <coroutine>` objects and instances of the
:class:`~collections.abc.Coroutine` ABC are all instances of this ABC.
.. note::
In CPython, generator-based coroutines (generators decorated with
:func:`types.coroutine` or :func:`asyncio.coroutine`) are
*awaitables*, even though they do not have an :meth:`__await__` method.
Using ``isinstance(gencoro, Awaitable)`` for them will return ``False``.
Use :func:`inspect.isawaitable` to detect them.
.. versionadded:: 3.5
.. class:: Coroutine
ABC for coroutine compatible classes. These implement the
following methods, defined in :ref:`coroutine-objects`:
:meth:`~coroutine.send`, :meth:`~coroutine.throw`, and
:meth:`~coroutine.close`. Custom implementations must also implement
:meth:`__await__`. All :class:`Coroutine` instances are also instances of
:class:`Awaitable`. See also the definition of :term:`coroutine`.
.. note::
In CPython, generator-based coroutines (generators decorated with
:func:`types.coroutine` or :func:`asyncio.coroutine`) are
*awaitables*, even though they do not have an :meth:`__await__` method.
Using ``isinstance(gencoro, Coroutine)`` for them will return ``False``.
Use :func:`inspect.isawaitable` to detect them.
.. versionadded:: 3.5
.. class:: AsyncIterable
ABC for classes that provide ``__aiter__`` method. See also the
definition of :term:`asynchronous iterable`.
.. versionadded:: 3.5
.. class:: AsyncIterator
ABC for classes that provide ``__aiter__`` and ``__anext__``
methods. See also the definition of :term:`asynchronous iterator`.
.. versionadded:: 3.5
.. class:: AsyncGenerator
ABC for asynchronous generator classes that implement the protocol
defined in :pep:`525` and :pep:`492`.
.. versionadded:: 3.6
These ABCs allow us to ask classes or instances if they provide
particular functionality, for example::
size = None
if isinstance(myvar, collections.abc.Sized):
size = len(myvar)
Several of the ABCs are also useful as mixins that make it easier to develop
classes supporting container APIs. For example, to write a class supporting
the full :class:`Set` API, it is only necessary to supply the three underlying
abstract methods: :meth:`__contains__`, :meth:`__iter__`, and :meth:`__len__`.
The ABC supplies the remaining methods such as :meth:`__and__` and
:meth:`isdisjoint`::
class ListBasedSet(collections.abc.Set):
''' Alternate set implementation favoring space over speed
and not requiring the set elements to be hashable. '''
def __init__(self, iterable):
self.elements = lst = []
for value in iterable:
if value not in lst:
lst.append(value)
def __iter__(self):
return iter(self.elements)
def __contains__(self, value):
return value in self.elements
def __len__(self):
return len(self.elements)
s1 = ListBasedSet('abcdef')
s2 = ListBasedSet('defghi')
overlap = s1 & s2 # The __and__() method is supported automatically
Notes on using :class:`Set` and :class:`MutableSet` as a mixin:
(1)
Since some set operations create new sets, the default mixin methods need
a way to create new instances from an iterable. The class constructor is
assumed to have a signature in the form ``ClassName(iterable)``.
That assumption is factored-out to an internal classmethod called
:meth:`_from_iterable` which calls ``cls(iterable)`` to produce a new set.
If the :class:`Set` mixin is being used in a class with a different
constructor signature, you will need to override :meth:`_from_iterable`
with a classmethod that can construct new instances from
an iterable argument.
(2)
To override the comparisons (presumably for speed, as the
semantics are fixed), redefine :meth:`__le__` and :meth:`__ge__`,
then the other operations will automatically follow suit.
(3)
The :class:`Set` mixin provides a :meth:`_hash` method to compute a hash value
for the set; however, :meth:`__hash__` is not defined because not all sets
are hashable or immutable. To add set hashability using mixins,
inherit from both :meth:`Set` and :meth:`Hashable`, then define
``__hash__ = Set._hash``.
.. seealso::
* `OrderedSet recipe <https://code.activestate.com/recipes/576694/>`_ for an
example built on :class:`MutableSet`.
* For more about ABCs, see the :mod:`abc` module and :pep:`3119`.

1256
web/python-docs/_sources/library/collections.rst.txt Normal file
View File

File diff suppressed because it is too large Load Diff

65
web/python-docs/_sources/library/colorsys.rst.txt Normal file
View File

@@ -0,0 +1,65 @@
: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
http://poynton.ca/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)

285
web/python-docs/_sources/library/compileall.rst.txt Normal file
View File

@@ -0,0 +1,285 @@
: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. If passed once, error messages will
still be printed. If passed twice (``-qq``), all output is suppressed.
.. 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``.
.. cmdoption:: -b
Write the byte-code files to their legacy locations and names, which may
overwrite byte-code files created by another version of Python. The default
is to write files to their :pep:`3147` locations and names, which allows
byte-code files from multiple versions of Python to coexist.
.. cmdoption:: -r
Control the maximum recursion level for subdirectories.
If this is given, then ``-l`` option will not be taken into account.
:program:`python -m compileall <directory> -r 0` is equivalent to
:program:`python -m compileall <directory> -l`.
.. cmdoption:: -j N
Use *N* workers to compile the files within the given directory.
If ``0`` is used, then the result of :func:`os.cpu_count()`
will be used.
.. cmdoption:: --invalidation-mode [timestamp|checked-hash|unchecked-hash]
Control how the generated byte-code files are invalidated at runtime.
The ``timestamp`` value, means that ``.pyc`` files with the source timestamp
and size embedded will be generated. The ``checked-hash`` and
``unchecked-hash`` values cause hash-based pycs to be generated. Hash-based
pycs embed a hash of the source file contents rather than a timestamp. See
:ref:`pyc-invalidation` for more information on how Python validates
bytecode cache files at runtime.
The default is ``timestamp`` if the :envvar:`SOURCE_DATE_EPOCH` environment
variable is not set, and ``checked-hash`` if the ``SOURCE_DATE_EPOCH``
environment variable is set.
.. versionchanged:: 3.2
Added the ``-i``, ``-b`` and ``-h`` options.
.. versionchanged:: 3.5
Added the ``-j``, ``-r``, and ``-qq`` options. ``-q`` option
was changed to a multilevel value. ``-b`` will always produce a
byte-code file ending in ``.pyc``, never ``.pyo``.
.. versionchanged:: 3.7
Added the ``--invalidation-mode`` option.
There is no command-line option to control the optimization level used by the
:func:`compile` function, because the Python interpreter itself already
provides the option: :program:`python -O -m compileall`.
Similarly, the :func:`compile` function respects the :attr:`sys.pycache_prefix`
setting. The generated bytecode cache will only be useful if :func:`compile` is
run with the same :attr:`sys.pycache_prefix` (if any) that will be used at
runtime.
Public functions
----------------
.. function:: compile_dir(dir, maxlevels=10, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1, invalidation_mode=None)
Recursively descend the directory tree named by *dir*, compiling all :file:`.py`
files along the way. Return a true value if all the files compiled successfully,
and a false value otherwise.
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 ``False`` or ``0`` (the default), the filenames and other
information are printed to standard out. Set to ``1``, only errors are
printed. Set to ``2``, all output is suppressed.
If *legacy* is true, byte-code files are written to their legacy locations
and names, which may overwrite byte-code files created by another version of
Python. The default is to write files to their :pep:`3147` locations and
names, which allows byte-code files from multiple versions of Python to
coexist.
*optimize* specifies the optimization level for the compiler. It is passed to
the built-in :func:`compile` function.
The argument *workers* specifies how many workers are used to
compile files in parallel. The default is to not use multiple workers.
If the platform can't use multiple workers and *workers* argument is given,
then sequential compilation will be used as a fallback. If *workers*
is 0, the number of cores in the system is used. If *workers* is
lower than ``0``, a :exc:`ValueError` will be raised.
*invalidation_mode* should be a member of the
:class:`py_compile.PycInvalidationMode` enum and controls how the generated
pycs are invalidated at runtime.
.. versionchanged:: 3.2
Added the *legacy* and *optimize* parameter.
.. versionchanged:: 3.5
Added the *workers* parameter.
.. versionchanged:: 3.5
*quiet* parameter was changed to a multilevel value.
.. versionchanged:: 3.5
The *legacy* parameter only writes out ``.pyc`` files, not ``.pyo`` files
no matter what the value of *optimize* is.
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
.. versionchanged:: 3.7
The *invalidation_mode* parameter was added.
.. versionchanged:: 3.7.2
The *invalidation_mode* parameter's default value is updated to None.
.. versionchanged:: 3.8
Setting *workers* to 0 now chooses the optimal number of cores.
.. function:: compile_file(fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, invalidation_mode=None)
Compile the file with path *fullname*. Return a true value if the file
compiled successfully, and a false value otherwise.
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 ``False`` or ``0`` (the default), the filenames and other
information are printed to standard out. Set to ``1``, only errors are
printed. Set to ``2``, all output is suppressed.
If *legacy* is true, byte-code files are written to their legacy locations
and names, which may overwrite byte-code files created by another version of
Python. The default is to write files to their :pep:`3147` locations and
names, which allows byte-code files from multiple versions of Python to
coexist.
*optimize* specifies the optimization level for the compiler. It is passed to
the built-in :func:`compile` function.
*invalidation_mode* should be a member of the
:class:`py_compile.PycInvalidationMode` enum and controls how the generated
pycs are invalidated at runtime.
.. versionadded:: 3.2
.. versionchanged:: 3.5
*quiet* parameter was changed to a multilevel value.
.. versionchanged:: 3.5
The *legacy* parameter only writes out ``.pyc`` files, not ``.pyo`` files
no matter what the value of *optimize* is.
.. versionchanged:: 3.7
The *invalidation_mode* parameter was added.
.. versionchanged:: 3.7.2
The *invalidation_mode* parameter's default value is updated to None.
.. function:: compile_path(skip_curdir=True, maxlevels=0, force=False, quiet=0, legacy=False, optimize=-1, invalidation_mode=None)
Byte-compile all the :file:`.py` files found along ``sys.path``. Return a
true value if all the files compiled successfully, and a false value otherwise.
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``.
.. versionchanged:: 3.2
Added the *legacy* and *optimize* parameter.
.. versionchanged:: 3.5
*quiet* parameter was changed to a multilevel value.
.. versionchanged:: 3.5
The *legacy* parameter only writes out ``.pyc`` files, not ``.pyo`` files
no matter what the value of *optimize* is.
.. versionchanged:: 3.7
The *invalidation_mode* parameter was added.
.. versionchanged:: 3.7.2
The *invalidation_mode* parameter's default value is updated to None.
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)
# pathlib.Path objects can also be used.
import pathlib
compileall.compile_dir(pathlib.Path('Lib/'), force=True)
.. seealso::
Module :mod:`py_compile`
Byte-compile a single source file.

33
web/python-docs/_sources/library/concurrency.rst.txt Normal file
View File

@@ -0,0 +1,33 @@
.. _concurrency:
********************
Concurrent Execution
********************
The modules described in this chapter provide support for concurrent
execution of code. The appropriate choice of tool will depend on the
task to be executed (CPU bound vs IO bound) and preferred style of
development (event driven cooperative multitasking vs preemptive
multitasking). Here's an overview:
.. toctree::
threading.rst
multiprocessing.rst
multiprocessing.shared_memory.rst
concurrent.rst
concurrent.futures.rst
subprocess.rst
sched.rst
queue.rst
contextvars.rst
The following are support modules for some of the above services:
.. toctree::
_thread.rst
_dummy_thread.rst
dummy_threading.rst

524
web/python-docs/_sources/library/concurrent.futures.rst.txt Normal file
View File

@@ -0,0 +1,524 @@
:mod:`concurrent.futures` --- Launching parallel tasks
======================================================
.. module:: concurrent.futures
:synopsis: Execute computations concurrently using threads or processes.
.. versionadded:: 3.2
**Source code:** :source:`Lib/concurrent/futures/thread.py`
and :source:`Lib/concurrent/futures/process.py`
--------------
The :mod:`concurrent.futures` module provides a high-level interface for
asynchronously executing callables.
The asynchronous execution can be performed with threads, using
:class:`ThreadPoolExecutor`, or separate processes, using
:class:`ProcessPoolExecutor`. Both implement the same interface, which is
defined by the abstract :class:`Executor` class.
Executor Objects
----------------
.. class:: Executor
An abstract class that provides methods to execute calls asynchronously. It
should not be used directly, but through its concrete subclasses.
.. method:: submit(fn, *args, **kwargs)
Schedules the callable, *fn*, to be executed as ``fn(*args **kwargs)``
and returns a :class:`Future` object representing the execution of the
callable. ::
with ThreadPoolExecutor(max_workers=1) as executor:
future = executor.submit(pow, 323, 1235)
print(future.result())
.. method:: map(func, *iterables, timeout=None, chunksize=1)
Similar to :func:`map(func, *iterables) <map>` except:
* the *iterables* are collected immediately rather than lazily;
* *func* is executed asynchronously and several calls to
*func* may be made concurrently.
The returned iterator raises a :exc:`concurrent.futures.TimeoutError`
if :meth:`~iterator.__next__` is called and the result isn't available
after *timeout* seconds from the original call to :meth:`Executor.map`.
*timeout* can be an int or a float. If *timeout* is not specified or
``None``, there is no limit to the wait time.
If a *func* call raises an exception, then that exception will be
raised when its value is retrieved from the iterator.
When using :class:`ProcessPoolExecutor`, this method chops *iterables*
into a number of chunks which it submits to the pool as separate
tasks. The (approximate) size of these chunks can be specified by
setting *chunksize* to a positive integer. For very long iterables,
using a large value for *chunksize* can significantly improve
performance compared to the default size of 1. With
:class:`ThreadPoolExecutor`, *chunksize* has no effect.
.. versionchanged:: 3.5
Added the *chunksize* argument.
.. method:: shutdown(wait=True)
Signal the executor that it should free any resources that it is using
when the currently pending futures are done executing. Calls to
:meth:`Executor.submit` and :meth:`Executor.map` made after shutdown will
raise :exc:`RuntimeError`.
If *wait* is ``True`` then this method will not return until all the
pending futures are done executing and the resources associated with the
executor have been freed. If *wait* is ``False`` then this method will
return immediately and the resources associated with the executor will be
freed when all pending futures are done executing. Regardless of the
value of *wait*, the entire Python program will not exit until all
pending futures are done executing.
You can avoid having to call this method explicitly if you use the
:keyword:`with` statement, which will shutdown the :class:`Executor`
(waiting as if :meth:`Executor.shutdown` were called with *wait* set to
``True``)::
import shutil
with ThreadPoolExecutor(max_workers=4) as e:
e.submit(shutil.copy, 'src1.txt', 'dest1.txt')
e.submit(shutil.copy, 'src2.txt', 'dest2.txt')
e.submit(shutil.copy, 'src3.txt', 'dest3.txt')
e.submit(shutil.copy, 'src4.txt', 'dest4.txt')
ThreadPoolExecutor
------------------
:class:`ThreadPoolExecutor` is an :class:`Executor` subclass that uses a pool of
threads to execute calls asynchronously.
Deadlocks can occur when the callable associated with a :class:`Future` waits on
the results of another :class:`Future`. For example::
import time
def wait_on_b():
time.sleep(5)
print(b.result()) # b will never complete because it is waiting on a.
return 5
def wait_on_a():
time.sleep(5)
print(a.result()) # a will never complete because it is waiting on b.
return 6
executor = ThreadPoolExecutor(max_workers=2)
a = executor.submit(wait_on_b)
b = executor.submit(wait_on_a)
And::
def wait_on_future():
f = executor.submit(pow, 5, 2)
# This will never complete because there is only one worker thread and
# it is executing this function.
print(f.result())
executor = ThreadPoolExecutor(max_workers=1)
executor.submit(wait_on_future)
.. class:: ThreadPoolExecutor(max_workers=None, thread_name_prefix='', initializer=None, initargs=())
An :class:`Executor` subclass that uses a pool of at most *max_workers*
threads to execute calls asynchronously.
*initializer* is an optional callable that is called at the start of
each worker thread; *initargs* is a tuple of arguments passed to the
initializer. Should *initializer* raise an exception, all currently
pending jobs will raise a :exc:`~concurrent.futures.thread.BrokenThreadPool`,
as well as any attempt to submit more jobs to the pool.
.. versionchanged:: 3.5
If *max_workers* is ``None`` or
not given, it will default to the number of processors on the machine,
multiplied by ``5``, assuming that :class:`ThreadPoolExecutor` is often
used to overlap I/O instead of CPU work and the number of workers
should be higher than the number of workers
for :class:`ProcessPoolExecutor`.
.. versionadded:: 3.6
The *thread_name_prefix* argument was added to allow users to
control the :class:`threading.Thread` names for worker threads created by
the pool for easier debugging.
.. versionchanged:: 3.7
Added the *initializer* and *initargs* arguments.
.. versionchanged:: 3.8
Default value of *max_workers* is changed to ``min(32, os.cpu_count() + 4)``.
This default value preserves at least 5 workers for I/O bound tasks.
It utilizes at most 32 CPU cores for CPU bound tasks which release the GIL.
And it avoids using very large resources implicitly on many-core machines.
ThreadPoolExecutor now reuses idle worker threads before starting
*max_workers* worker threads too.
.. _threadpoolexecutor-example:
ThreadPoolExecutor Example
~~~~~~~~~~~~~~~~~~~~~~~~~~
::
import concurrent.futures
import urllib.request
URLS = ['http://www.foxnews.com/',
'http://www.cnn.com/',
'http://europe.wsj.com/',
'http://www.bbc.co.uk/',
'http://nonexistant-subdomain.python.org/']
# Retrieve a single page and report the URL and contents
def load_url(url, timeout):
with urllib.request.urlopen(url, timeout=timeout) as conn:
return conn.read()
# We can use a with statement to ensure threads are cleaned up promptly
with concurrent.futures.ThreadPoolExecutor(max_workers=5) as executor:
# Start the load operations and mark each future with its URL
future_to_url = {executor.submit(load_url, url, 60): url for url in URLS}
for future in concurrent.futures.as_completed(future_to_url):
url = future_to_url[future]
try:
data = future.result()
except Exception as exc:
print('%r generated an exception: %s' % (url, exc))
else:
print('%r page is %d bytes' % (url, len(data)))
ProcessPoolExecutor
-------------------
The :class:`ProcessPoolExecutor` class is an :class:`Executor` subclass that
uses a pool of processes to execute calls asynchronously.
:class:`ProcessPoolExecutor` uses the :mod:`multiprocessing` module, which
allows it to side-step the :term:`Global Interpreter Lock
<global interpreter lock>` but also means that
only picklable objects can be executed and returned.
The ``__main__`` module must be importable by worker subprocesses. This means
that :class:`ProcessPoolExecutor` will not work in the interactive interpreter.
Calling :class:`Executor` or :class:`Future` methods from a callable submitted
to a :class:`ProcessPoolExecutor` will result in deadlock.
.. class:: ProcessPoolExecutor(max_workers=None, mp_context=None, initializer=None, initargs=())
An :class:`Executor` subclass that executes calls asynchronously using a pool
of at most *max_workers* processes. If *max_workers* is ``None`` or not
given, it will default to the number of processors on the machine.
If *max_workers* is less than or equal to ``0``, then a :exc:`ValueError`
will be raised.
On Windows, *max_workers* must be less than or equal to ``61``. If it is not
then :exc:`ValueError` will be raised. If *max_workers* is ``None``, then
the default chosen will be at most ``61``, even if more processors are
available.
*mp_context* can be a multiprocessing context or None. It will be used to
launch the workers. If *mp_context* is ``None`` or not given, the default
multiprocessing context is used.
*initializer* is an optional callable that is called at the start of
each worker process; *initargs* is a tuple of arguments passed to the
initializer. Should *initializer* raise an exception, all currently
pending jobs will raise a :exc:`~concurrent.futures.process.BrokenProcessPool`,
as well as any attempt to submit more jobs to the pool.
.. versionchanged:: 3.3
When one of the worker processes terminates abruptly, a
:exc:`BrokenProcessPool` error is now raised. Previously, behaviour
was undefined but operations on the executor or its futures would often
freeze or deadlock.
.. versionchanged:: 3.7
The *mp_context* argument was added to allow users to control the
start_method for worker processes created by the pool.
Added the *initializer* and *initargs* arguments.
.. _processpoolexecutor-example:
ProcessPoolExecutor Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
import concurrent.futures
import math
PRIMES = [
112272535095293,
112582705942171,
112272535095293,
115280095190773,
115797848077099,
1099726899285419]
def is_prime(n):
if n < 2:
return False
if n == 2:
return True
if n % 2 == 0:
return False
sqrt_n = int(math.floor(math.sqrt(n)))
for i in range(3, sqrt_n + 1, 2):
if n % i == 0:
return False
return True
def main():
with concurrent.futures.ProcessPoolExecutor() as executor:
for number, prime in zip(PRIMES, executor.map(is_prime, PRIMES)):
print('%d is prime: %s' % (number, prime))
if __name__ == '__main__':
main()
Future Objects
--------------
The :class:`Future` class encapsulates the asynchronous execution of a callable.
:class:`Future` instances are created by :meth:`Executor.submit`.
.. class:: Future
Encapsulates the asynchronous execution of a callable. :class:`Future`
instances are created by :meth:`Executor.submit` and should not be created
directly except for testing.
.. method:: cancel()
Attempt to cancel the call. If the call is currently being executed or
finished running and cannot be cancelled then the method will return
``False``, otherwise the call will be cancelled and the method will
return ``True``.
.. method:: cancelled()
Return ``True`` if the call was successfully cancelled.
.. method:: running()
Return ``True`` if the call is currently being executed and cannot be
cancelled.
.. method:: done()
Return ``True`` if the call was successfully cancelled or finished
running.
.. method:: result(timeout=None)
Return the value returned by the call. If the call hasn't yet completed
then this method will wait up to *timeout* seconds. If the call hasn't
completed in *timeout* seconds, then a
:exc:`concurrent.futures.TimeoutError` will be raised. *timeout* can be
an int or float. If *timeout* is not specified or ``None``, there is no
limit to the wait time.
If the future is cancelled before completing then :exc:`.CancelledError`
will be raised.
If the call raised, this method will raise the same exception.
.. method:: exception(timeout=None)
Return the exception raised by the call. If the call hasn't yet
completed then this method will wait up to *timeout* seconds. If the
call hasn't completed in *timeout* seconds, then a
:exc:`concurrent.futures.TimeoutError` will be raised. *timeout* can be
an int or float. If *timeout* is not specified or ``None``, there is no
limit to the wait time.
If the future is cancelled before completing then :exc:`.CancelledError`
will be raised.
If the call completed without raising, ``None`` is returned.
.. method:: add_done_callback(fn)
Attaches the callable *fn* to the future. *fn* will be called, with the
future as its only argument, when the future is cancelled or finishes
running.
Added callables are called in the order that they were added and are
always called in a thread belonging to the process that added them. If
the callable raises an :exc:`Exception` subclass, it will be logged and
ignored. If the callable raises a :exc:`BaseException` subclass, the
behavior is undefined.
If the future has already completed or been cancelled, *fn* will be
called immediately.
The following :class:`Future` methods are meant for use in unit tests and
:class:`Executor` implementations.
.. method:: set_running_or_notify_cancel()
This method should only be called by :class:`Executor` implementations
before executing the work associated with the :class:`Future` and by unit
tests.
If the method returns ``False`` then the :class:`Future` was cancelled,
i.e. :meth:`Future.cancel` was called and returned `True`. Any threads
waiting on the :class:`Future` completing (i.e. through
:func:`as_completed` or :func:`wait`) will be woken up.
If the method returns ``True`` then the :class:`Future` was not cancelled
and has been put in the running state, i.e. calls to
:meth:`Future.running` will return `True`.
This method can only be called once and cannot be called after
:meth:`Future.set_result` or :meth:`Future.set_exception` have been
called.
.. method:: set_result(result)
Sets the result of the work associated with the :class:`Future` to
*result*.
This method should only be used by :class:`Executor` implementations and
unit tests.
.. versionchanged:: 3.8
This method raises
:exc:`concurrent.futures.InvalidStateError` if the :class:`Future` is
already done.
.. method:: set_exception(exception)
Sets the result of the work associated with the :class:`Future` to the
:class:`Exception` *exception*.
This method should only be used by :class:`Executor` implementations and
unit tests.
.. versionchanged:: 3.8
This method raises
:exc:`concurrent.futures.InvalidStateError` if the :class:`Future` is
already done.
Module Functions
----------------
.. function:: wait(fs, timeout=None, return_when=ALL_COMPLETED)
Wait for the :class:`Future` instances (possibly created by different
:class:`Executor` instances) given by *fs* to complete. Returns a named
2-tuple of sets. The first set, named ``done``, contains the futures that
completed (finished or cancelled futures) before the wait completed. The
second set, named ``not_done``, contains the futures that did not complete
(pending or running futures).
*timeout* can be used to control the maximum number of seconds to wait before
returning. *timeout* can be an int or float. If *timeout* is not specified
or ``None``, there is no limit to the wait time.
*return_when* indicates when this function should return. It must be one of
the following constants:
.. tabularcolumns:: |l|L|
+-----------------------------+----------------------------------------+
| Constant | Description |
+=============================+========================================+
| :const:`FIRST_COMPLETED` | The function will return when any |
| | future finishes or is cancelled. |
+-----------------------------+----------------------------------------+
| :const:`FIRST_EXCEPTION` | The function will return when any |
| | future finishes by raising an |
| | exception. If no future raises an |
| | exception then it is equivalent to |
| | :const:`ALL_COMPLETED`. |
+-----------------------------+----------------------------------------+
| :const:`ALL_COMPLETED` | The function will return when all |
| | futures finish or are cancelled. |
+-----------------------------+----------------------------------------+
.. function:: as_completed(fs, timeout=None)
Returns an iterator over the :class:`Future` instances (possibly created by
different :class:`Executor` instances) given by *fs* that yields futures as
they complete (finished or cancelled futures). Any futures given by *fs* that
are duplicated will be returned once. Any futures that completed before
:func:`as_completed` is called will be yielded first. The returned iterator
raises a :exc:`concurrent.futures.TimeoutError` if :meth:`~iterator.__next__`
is called and the result isn't available after *timeout* seconds from the
original call to :func:`as_completed`. *timeout* can be an int or float. If
*timeout* is not specified or ``None``, there is no limit to the wait time.
.. seealso::
:pep:`3148` -- futures - execute computations asynchronously
The proposal which described this feature for inclusion in the Python
standard library.
Exception classes
-----------------
.. currentmodule:: concurrent.futures
.. exception:: CancelledError
Raised when a future is cancelled.
.. exception:: TimeoutError
Raised when a future operation exceeds the given timeout.
.. exception:: BrokenExecutor
Derived from :exc:`RuntimeError`, this exception class is raised
when an executor is broken for some reason, and cannot be used
to submit or execute new tasks.
.. versionadded:: 3.7
.. exception:: InvalidStateError
Raised when an operation is performed on a future that is not allowed
in the current state.
.. versionadded:: 3.8
.. currentmodule:: concurrent.futures.thread
.. exception:: BrokenThreadPool
Derived from :exc:`~concurrent.futures.BrokenExecutor`, this exception
class is raised when one of the workers of a :class:`ThreadPoolExecutor`
has failed initializing.
.. versionadded:: 3.7
.. currentmodule:: concurrent.futures.process
.. exception:: BrokenProcessPool
Derived from :exc:`~concurrent.futures.BrokenExecutor` (formerly
:exc:`RuntimeError`), this exception class is raised when one of the
workers of a :class:`ProcessPoolExecutor` has terminated in a non-clean
fashion (for example, if it was killed from the outside).
.. versionadded:: 3.3

6
web/python-docs/_sources/library/concurrent.rst.txt Normal file
View File

@@ -0,0 +1,6 @@
The :mod:`concurrent` package
=============================
Currently, there is only one module in this package:
* :mod:`concurrent.futures` -- Launching parallel tasks

1331
web/python-docs/_sources/library/configparser.rst.txt Normal file
View File

File diff suppressed because it is too large Load Diff

99
web/python-docs/_sources/library/constants.rst.txt Normal file
View File

@@ -0,0 +1,99 @@
.. _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. Assignments to ``False``
are illegal and raise a :exc:`SyntaxError`.
.. data:: True
The true value of the :class:`bool` type. Assignments to ``True``
are illegal and raise a :exc:`SyntaxError`.
.. data:: None
The sole value of the type ``NoneType``. ``None`` is frequently used to
represent the absence of a value, as when default arguments are not passed to a
function. Assignments to ``None`` are illegal and raise a :exc:`SyntaxError`.
.. data:: NotImplemented
Special value which should be returned by the binary special methods
(e.g. :meth:`__eq__`, :meth:`__lt__`, :meth:`__add__`, :meth:`__rsub__`,
etc.) to indicate that the operation is not implemented with respect to
the other type; may be returned by the in-place binary special methods
(e.g. :meth:`__imul__`, :meth:`__iand__`, etc.) for the same purpose.
Its truth value is true.
.. note::
When a binary (or in-place) method returns ``NotImplemented`` the
interpreter will try the reflected operation on the other type (or some
other fallback, depending on the operator). If all attempts return
``NotImplemented``, the interpreter will raise an appropriate exception.
Incorrectly returning ``NotImplemented`` will result in a misleading
error message or the ``NotImplemented`` value being returned to Python code.
See :ref:`implementing-the-arithmetic-operations` for examples.
.. note::
``NotImplementedError`` and ``NotImplemented`` are not interchangeable,
even though they have similar names and purposes.
See :exc:`NotImplementedError` for details on when to use it.
.. index:: single: ...; ellipsis literal
.. data:: Ellipsis
The same as the ellipsis literal "``...``". Special value used mostly in conjunction
with extended slicing syntax for user-defined container data types.
.. 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`, :data:`False`, :data:`True` and :data:`__debug__`
cannot be reassigned (assignments to them, even as an attribute name, raise
:exc:`SyntaxError`), so they can be considered "true" constants.
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).

872
web/python-docs/_sources/library/contextlib.rst.txt Normal file
View File

@@ -0,0 +1,872 @@
:mod:`!contextlib` --- Utilities for :keyword:`!with`\ -statement contexts
==========================================================================
.. module:: contextlib
:synopsis: Utilities for with-statement contexts.
**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`.
Utilities
---------
Functions and classes provided:
.. class:: AbstractContextManager
An :term:`abstract base class` for classes that implement
:meth:`object.__enter__` and :meth:`object.__exit__`. A default
implementation for :meth:`object.__enter__` is provided which returns
``self`` while :meth:`object.__exit__` is an abstract method which by default
returns ``None``. See also the definition of :ref:`typecontextmanager`.
.. versionadded:: 3.6
.. class:: AbstractAsyncContextManager
An :term:`abstract base class` for classes that implement
:meth:`object.__aenter__` and :meth:`object.__aexit__`. A default
implementation for :meth:`object.__aenter__` is provided which returns
``self`` while :meth:`object.__aexit__` is an abstract method which by default
returns ``None``. See also the definition of
:ref:`async-context-managers`.
.. versionadded:: 3.7
.. decorator:: contextmanager
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.
:func:`contextmanager` uses :class:`ContextDecorator` so the context managers
it creates can be used as decorators as well as in :keyword:`with` statements.
When used as a decorator, a new generator instance is implicitly created on
each function call (this allows the otherwise "one-shot" context managers
created by :func:`contextmanager` to meet the requirement that context
managers support multiple invocations in order to be used as decorators).
.. versionchanged:: 3.2
Use of :class:`ContextDecorator`.
.. decorator:: asynccontextmanager
Similar to :func:`~contextlib.contextmanager`, but creates an
:ref:`asynchronous context manager <async-context-managers>`.
This function is a :term:`decorator` that can be used to define a factory
function for :keyword:`async with` statement asynchronous context managers,
without needing to create a class or separate :meth:`__aenter__` and
:meth:`__aexit__` methods. It must be applied to an :term:`asynchronous
generator` function.
A simple example::
from contextlib import asynccontextmanager
@asynccontextmanager
async def get_connection():
conn = await acquire_db_connection()
try:
yield conn
finally:
await release_db_connection(conn)
async def get_all_users():
async with get_connection() as conn:
return conn.query('SELECT ...')
.. versionadded:: 3.7
.. 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
from urllib.request import urlopen
with closing(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.
.. _simplifying-support-for-single-optional-context-managers:
.. function:: nullcontext(enter_result=None)
Return a context manager that returns *enter_result* from ``__enter__``, but
otherwise does nothing. It is intended to be used as a stand-in for an
optional context manager, for example::
def myfunction(arg, ignore_exceptions=False):
if ignore_exceptions:
# Use suppress to ignore all exceptions.
cm = contextlib.suppress(Exception)
else:
# Do not ignore any exceptions, cm has no effect.
cm = contextlib.nullcontext()
with cm:
# Do something
An example using *enter_result*::
def process_file(file_or_path):
if isinstance(file_or_path, str):
# If string, open file
cm = open(file_or_path)
else:
# Caller is responsible for closing file
cm = nullcontext(file_or_path)
with cm as file:
# Perform processing on the file
.. versionadded:: 3.7
.. function:: suppress(*exceptions)
Return a context manager that suppresses any of the specified exceptions
if they occur in the body of a with statement and then resumes execution
with the first statement following the end of the with statement.
As with any other mechanism that completely suppresses exceptions, this
context manager should be used only to cover very specific errors where
silently continuing with program execution is known to be the right
thing to do.
For example::
from contextlib import suppress
with suppress(FileNotFoundError):
os.remove('somefile.tmp')
with suppress(FileNotFoundError):
os.remove('someotherfile.tmp')
This code is equivalent to::
try:
os.remove('somefile.tmp')
except FileNotFoundError:
pass
try:
os.remove('someotherfile.tmp')
except FileNotFoundError:
pass
This context manager is :ref:`reentrant <reentrant-cms>`.
.. versionadded:: 3.4
.. function:: redirect_stdout(new_target)
Context manager for temporarily redirecting :data:`sys.stdout` to
another file or file-like object.
This tool adds flexibility to existing functions or classes whose output
is hardwired to stdout.
For example, the output of :func:`help` normally is sent to *sys.stdout*.
You can capture that output in a string by redirecting the output to an
:class:`io.StringIO` object::
f = io.StringIO()
with redirect_stdout(f):
help(pow)
s = f.getvalue()
To send the output of :func:`help` to a file on disk, redirect the output
to a regular file::
with open('help.txt', 'w') as f:
with redirect_stdout(f):
help(pow)
To send the output of :func:`help` to *sys.stderr*::
with redirect_stdout(sys.stderr):
help(pow)
Note that the global side effect on :data:`sys.stdout` means that this
context manager is not suitable for use in library code and most threaded
applications. It also has no effect on the output of subprocesses.
However, it is still a useful approach for many utility scripts.
This context manager is :ref:`reentrant <reentrant-cms>`.
.. versionadded:: 3.4
.. function:: redirect_stderr(new_target)
Similar to :func:`~contextlib.redirect_stdout` but redirecting
:data:`sys.stderr` to another file or file-like object.
This context manager is :ref:`reentrant <reentrant-cms>`.
.. versionadded:: 3.5
.. class:: ContextDecorator()
A base class that enables a context manager to also be used as a decorator.
Context managers inheriting from ``ContextDecorator`` have to implement
``__enter__`` and ``__exit__`` as normal. ``__exit__`` retains its optional
exception handling even when used as a decorator.
``ContextDecorator`` is used by :func:`contextmanager`, so you get this
functionality automatically.
Example of ``ContextDecorator``::
from contextlib import ContextDecorator
class mycontext(ContextDecorator):
def __enter__(self):
print('Starting')
return self
def __exit__(self, *exc):
print('Finishing')
return False
>>> @mycontext()
... def function():
... print('The bit in the middle')
...
>>> function()
Starting
The bit in the middle
Finishing
>>> with mycontext():
... print('The bit in the middle')
...
Starting
The bit in the middle
Finishing
This change is just syntactic sugar for any construct of the following form::
def f():
with cm():
# Do stuff
``ContextDecorator`` lets you instead write::
@cm()
def f():
# Do stuff
It makes it clear that the ``cm`` applies to the whole function, rather than
just a piece of it (and saving an indentation level is nice, too).
Existing context managers that already have a base class can be extended by
using ``ContextDecorator`` as a mixin class::
from contextlib import ContextDecorator
class mycontext(ContextBaseClass, ContextDecorator):
def __enter__(self):
return self
def __exit__(self, *exc):
return False
.. note::
As the decorated function must be able to be called multiple times, the
underlying context manager must support use in multiple :keyword:`with`
statements. If this is not the case, then the original construct with the
explicit :keyword:`!with` statement inside the function should be used.
.. versionadded:: 3.2
.. class:: ExitStack()
A context manager that is designed to make it easy to programmatically
combine other context managers and cleanup functions, especially those
that are optional or otherwise driven by input data.
For example, a set of files may easily be handled in a single with
statement as follows::
with ExitStack() as stack:
files = [stack.enter_context(open(fname)) for fname in filenames]
# All opened files will automatically be closed at the end of
# the with statement, even if attempts to open files later
# in the list raise an exception
Each instance maintains a stack of registered callbacks that are called in
reverse order when the instance is closed (either explicitly or implicitly
at the end of a :keyword:`with` statement). Note that callbacks are *not*
invoked implicitly when the context stack instance is garbage collected.
This stack model is used so that context managers that acquire their
resources in their ``__init__`` method (such as file objects) can be
handled correctly.
Since registered callbacks are invoked in the reverse order of
registration, this ends up behaving as if multiple nested :keyword:`with`
statements had been used with the registered set of callbacks. This even
extends to exception handling - if an inner callback suppresses or replaces
an exception, then outer callbacks will be passed arguments based on that
updated state.
This is a relatively low level API that takes care of the details of
correctly unwinding the stack of exit callbacks. It provides a suitable
foundation for higher level context managers that manipulate the exit
stack in application specific ways.
.. versionadded:: 3.3
.. method:: enter_context(cm)
Enters a new context manager and adds its :meth:`__exit__` method to
the callback stack. The return value is the result of the context
manager's own :meth:`__enter__` method.
These context managers may suppress exceptions just as they normally
would if used directly as part of a :keyword:`with` statement.
.. method:: push(exit)
Adds a context manager's :meth:`__exit__` method to the callback stack.
As ``__enter__`` is *not* invoked, this method can be used to cover
part of an :meth:`__enter__` implementation with a context manager's own
:meth:`__exit__` method.
If passed an object that is not a context manager, this method assumes
it is a callback with the same signature as a context manager's
:meth:`__exit__` method and adds it directly to the callback stack.
By returning true values, these callbacks can suppress exceptions the
same way context manager :meth:`__exit__` methods can.
The passed in object is returned from the function, allowing this
method to be used as a function decorator.
.. method:: callback(callback, *args, **kwds)
Accepts an arbitrary callback function and arguments and adds it to
the callback stack.
Unlike the other methods, callbacks added this way cannot suppress
exceptions (as they are never passed the exception details).
The passed in callback is returned from the function, allowing this
method to be used as a function decorator.
.. method:: pop_all()
Transfers the callback stack to a fresh :class:`ExitStack` instance
and returns it. No callbacks are invoked by this operation - instead,
they will now be invoked when the new stack is closed (either
explicitly or implicitly at the end of a :keyword:`with` statement).
For example, a group of files can be opened as an "all or nothing"
operation as follows::
with ExitStack() as stack:
files = [stack.enter_context(open(fname)) for fname in filenames]
# Hold onto the close method, but don't call it yet.
close_files = stack.pop_all().close
# If opening any file fails, all previously opened files will be
# closed automatically. If all files are opened successfully,
# they will remain open even after the with statement ends.
# close_files() can then be invoked explicitly to close them all.
.. method:: close()
Immediately unwinds the callback stack, invoking callbacks in the
reverse order of registration. For any context managers and exit
callbacks registered, the arguments passed in will indicate that no
exception occurred.
.. class:: AsyncExitStack()
An :ref:`asynchronous context manager <async-context-managers>`, similar
to :class:`ExitStack`, that supports combining both synchronous and
asynchronous context managers, as well as having coroutines for
cleanup logic.
The :meth:`close` method is not implemented, :meth:`aclose` must be used
instead.
.. method:: enter_async_context(cm)
Similar to :meth:`enter_context` but expects an asynchronous context
manager.
.. method:: push_async_exit(exit)
Similar to :meth:`push` but expects either an asynchronous context manager
or a coroutine function.
.. method:: push_async_callback(callback, *args, **kwds)
Similar to :meth:`callback` but expects a coroutine function.
.. method:: aclose()
Similar to :meth:`close` but properly handles awaitables.
Continuing the example for :func:`asynccontextmanager`::
async with AsyncExitStack() as stack:
connections = [await stack.enter_async_context(get_connection())
for i in range(5)]
# All opened connections will automatically be released at the end of
# the async with statement, even if attempts to open a connection
# later in the list raise an exception.
.. versionadded:: 3.7
Examples and Recipes
--------------------
This section describes some examples and recipes for making effective use of
the tools provided by :mod:`contextlib`.
Supporting a variable number of context managers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The primary use case for :class:`ExitStack` is the one given in the class
documentation: supporting a variable number of context managers and other
cleanup operations in a single :keyword:`with` statement. The variability
may come from the number of context managers needed being driven by user
input (such as opening a user specified collection of files), or from
some of the context managers being optional::
with ExitStack() as stack:
for resource in resources:
stack.enter_context(resource)
if need_special_resource():
special = acquire_special_resource()
stack.callback(release_special_resource, special)
# Perform operations that use the acquired resources
As shown, :class:`ExitStack` also makes it quite easy to use :keyword:`with`
statements to manage arbitrary resources that don't natively support the
context management protocol.
Catching exceptions from ``__enter__`` methods
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
It is occasionally desirable to catch exceptions from an ``__enter__``
method implementation, *without* inadvertently catching exceptions from
the :keyword:`with` statement body or the context manager's ``__exit__``
method. By using :class:`ExitStack` the steps in the context management
protocol can be separated slightly in order to allow this::
stack = ExitStack()
try:
x = stack.enter_context(cm)
except Exception:
# handle __enter__ exception
else:
with stack:
# Handle normal case
Actually needing to do this is likely to indicate that the underlying API
should be providing a direct resource management interface for use with
:keyword:`try`/:keyword:`except`/:keyword:`finally` statements, but not
all APIs are well designed in that regard. When a context manager is the
only resource management API provided, then :class:`ExitStack` can make it
easier to handle various situations that can't be handled directly in a
:keyword:`with` statement.
Cleaning up in an ``__enter__`` implementation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
As noted in the documentation of :meth:`ExitStack.push`, this
method can be useful in cleaning up an already allocated resource if later
steps in the :meth:`__enter__` implementation fail.
Here's an example of doing this for a context manager that accepts resource
acquisition and release functions, along with an optional validation function,
and maps them to the context management protocol::
from contextlib import contextmanager, AbstractContextManager, ExitStack
class ResourceManager(AbstractContextManager):
def __init__(self, acquire_resource, release_resource, check_resource_ok=None):
self.acquire_resource = acquire_resource
self.release_resource = release_resource
if check_resource_ok is None:
def check_resource_ok(resource):
return True
self.check_resource_ok = check_resource_ok
@contextmanager
def _cleanup_on_error(self):
with ExitStack() as stack:
stack.push(self)
yield
# The validation check passed and didn't raise an exception
# Accordingly, we want to keep the resource, and pass it
# back to our caller
stack.pop_all()
def __enter__(self):
resource = self.acquire_resource()
with self._cleanup_on_error():
if not self.check_resource_ok(resource):
msg = "Failed validation for {!r}"
raise RuntimeError(msg.format(resource))
return resource
def __exit__(self, *exc_details):
# We don't need to duplicate any of our resource release logic
self.release_resource()
Replacing any use of ``try-finally`` and flag variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A pattern you will sometimes see is a ``try-finally`` statement with a flag
variable to indicate whether or not the body of the ``finally`` clause should
be executed. In its simplest form (that can't already be handled just by
using an ``except`` clause instead), it looks something like this::
cleanup_needed = True
try:
result = perform_operation()
if result:
cleanup_needed = False
finally:
if cleanup_needed:
cleanup_resources()
As with any ``try`` statement based code, this can cause problems for
development and review, because the setup code and the cleanup code can end
up being separated by arbitrarily long sections of code.
:class:`ExitStack` makes it possible to instead register a callback for
execution at the end of a ``with`` statement, and then later decide to skip
executing that callback::
from contextlib import ExitStack
with ExitStack() as stack:
stack.callback(cleanup_resources)
result = perform_operation()
if result:
stack.pop_all()
This allows the intended cleanup up behaviour to be made explicit up front,
rather than requiring a separate flag variable.
If a particular application uses this pattern a lot, it can be simplified
even further by means of a small helper class::
from contextlib import ExitStack
class Callback(ExitStack):
def __init__(self, callback, /, *args, **kwds):
super().__init__()
self.callback(callback, *args, **kwds)
def cancel(self):
self.pop_all()
with Callback(cleanup_resources) as cb:
result = perform_operation()
if result:
cb.cancel()
If the resource cleanup isn't already neatly bundled into a standalone
function, then it is still possible to use the decorator form of
:meth:`ExitStack.callback` to declare the resource cleanup in
advance::
from contextlib import ExitStack
with ExitStack() as stack:
@stack.callback
def cleanup_resources():
...
result = perform_operation()
if result:
stack.pop_all()
Due to the way the decorator protocol works, a callback function
declared this way cannot take any parameters. Instead, any resources to
be released must be accessed as closure variables.
Using a context manager as a function decorator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:class:`ContextDecorator` makes it possible to use a context manager in
both an ordinary ``with`` statement and also as a function decorator.
For example, it is sometimes useful to wrap functions or groups of statements
with a logger that can track the time of entry and time of exit. Rather than
writing both a function decorator and a context manager for the task,
inheriting from :class:`ContextDecorator` provides both capabilities in a
single definition::
from contextlib import ContextDecorator
import logging
logging.basicConfig(level=logging.INFO)
class track_entry_and_exit(ContextDecorator):
def __init__(self, name):
self.name = name
def __enter__(self):
logging.info('Entering: %s', self.name)
def __exit__(self, exc_type, exc, exc_tb):
logging.info('Exiting: %s', self.name)
Instances of this class can be used as both a context manager::
with track_entry_and_exit('widget loader'):
print('Some time consuming activity goes here')
load_widget()
And also as a function decorator::
@track_entry_and_exit('widget loader')
def activity():
print('Some time consuming activity goes here')
load_widget()
Note that there is one additional limitation when using context managers
as function decorators: there's no way to access the return value of
:meth:`__enter__`. If that value is needed, then it is still necessary to use
an explicit ``with`` statement.
.. seealso::
:pep:`343` - The "with" statement
The specification, background, and examples for the Python :keyword:`with`
statement.
.. _single-use-reusable-and-reentrant-cms:
Single use, reusable and reentrant context managers
---------------------------------------------------
Most context managers are written in a way that means they can only be
used effectively in a :keyword:`with` statement once. These single use
context managers must be created afresh each time they're used -
attempting to use them a second time will trigger an exception or
otherwise not work correctly.
This common limitation means that it is generally advisable to create
context managers directly in the header of the :keyword:`with` statement
where they are used (as shown in all of the usage examples above).
Files are an example of effectively single use context managers, since
the first :keyword:`with` statement will close the file, preventing any
further IO operations using that file object.
Context managers created using :func:`contextmanager` are also single use
context managers, and will complain about the underlying generator failing
to yield if an attempt is made to use them a second time::
>>> from contextlib import contextmanager
>>> @contextmanager
... def singleuse():
... print("Before")
... yield
... print("After")
...
>>> cm = singleuse()
>>> with cm:
... pass
...
Before
After
>>> with cm:
... pass
...
Traceback (most recent call last):
...
RuntimeError: generator didn't yield
.. _reentrant-cms:
Reentrant context managers
^^^^^^^^^^^^^^^^^^^^^^^^^^
More sophisticated context managers may be "reentrant". These context
managers can not only be used in multiple :keyword:`with` statements,
but may also be used *inside* a :keyword:`!with` statement that is already
using the same context manager.
:class:`threading.RLock` is an example of a reentrant context manager, as are
:func:`suppress` and :func:`redirect_stdout`. Here's a very simple example of
reentrant use::
>>> from contextlib import redirect_stdout
>>> from io import StringIO
>>> stream = StringIO()
>>> write_to_stream = redirect_stdout(stream)
>>> with write_to_stream:
... print("This is written to the stream rather than stdout")
... with write_to_stream:
... print("This is also written to the stream")
...
>>> print("This is written directly to stdout")
This is written directly to stdout
>>> print(stream.getvalue())
This is written to the stream rather than stdout
This is also written to the stream
Real world examples of reentrancy are more likely to involve multiple
functions calling each other and hence be far more complicated than this
example.
Note also that being reentrant is *not* the same thing as being thread safe.
:func:`redirect_stdout`, for example, is definitely not thread safe, as it
makes a global modification to the system state by binding :data:`sys.stdout`
to a different stream.
.. _reusable-cms:
Reusable context managers
^^^^^^^^^^^^^^^^^^^^^^^^^
Distinct from both single use and reentrant context managers are "reusable"
context managers (or, to be completely explicit, "reusable, but not
reentrant" context managers, since reentrant context managers are also
reusable). These context managers support being used multiple times, but
will fail (or otherwise not work correctly) if the specific context manager
instance has already been used in a containing with statement.
:class:`threading.Lock` is an example of a reusable, but not reentrant,
context manager (for a reentrant lock, it is necessary to use
:class:`threading.RLock` instead).
Another example of a reusable, but not reentrant, context manager is
:class:`ExitStack`, as it invokes *all* currently registered callbacks
when leaving any with statement, regardless of where those callbacks
were added::
>>> from contextlib import ExitStack
>>> stack = ExitStack()
>>> with stack:
... stack.callback(print, "Callback: from first context")
... print("Leaving first context")
...
Leaving first context
Callback: from first context
>>> with stack:
... stack.callback(print, "Callback: from second context")
... print("Leaving second context")
...
Leaving second context
Callback: from second context
>>> with stack:
... stack.callback(print, "Callback: from outer context")
... with stack:
... stack.callback(print, "Callback: from inner context")
... print("Leaving inner context")
... print("Leaving outer context")
...
Leaving inner context
Callback: from inner context
Callback: from outer context
Leaving outer context
As the output from the example shows, reusing a single stack object across
multiple with statements works correctly, but attempting to nest them
will cause the stack to be cleared at the end of the innermost with
statement, which is unlikely to be desirable behaviour.
Using separate :class:`ExitStack` instances instead of reusing a single
instance avoids that problem::
>>> from contextlib import ExitStack
>>> with ExitStack() as outer_stack:
... outer_stack.callback(print, "Callback: from outer context")
... with ExitStack() as inner_stack:
... inner_stack.callback(print, "Callback: from inner context")
... print("Leaving inner context")
... print("Leaving outer context")
...
Leaving inner context
Callback: from inner context
Leaving outer context
Callback: from outer context

281
web/python-docs/_sources/library/contextvars.rst.txt Normal file
View File

@@ -0,0 +1,281 @@
:mod:`contextvars` --- Context Variables
========================================
.. module:: contextvars
:synopsis: Context Variables
.. sectionauthor:: Yury Selivanov <yury@magic.io>
--------------
This module provides APIs to manage, store, and access context-local
state. The :class:`~contextvars.ContextVar` class is used to declare
and work with *Context Variables*. The :func:`~contextvars.copy_context`
function and the :class:`~contextvars.Context` class should be used to
manage the current context in asynchronous frameworks.
Context managers that have state should use Context Variables
instead of :func:`threading.local()` to prevent their state from
bleeding to other code unexpectedly, when used in concurrent code.
See also :pep:`567` for additional details.
.. versionadded:: 3.7
Context Variables
-----------------
.. class:: ContextVar(name, [*, default])
This class is used to declare a new Context Variable, e.g.::
var: ContextVar[int] = ContextVar('var', default=42)
The required *name* parameter is used for introspection and debug
purposes.
The optional keyword-only *default* parameter is returned by
:meth:`ContextVar.get` when no value for the variable is found
in the current context.
**Important:** Context Variables should be created at the top module
level and never in closures. :class:`Context` objects hold strong
references to context variables which prevents context variables
from being properly garbage collected.
.. attribute:: ContextVar.name
The name of the variable. This is a read-only property.
.. versionadded:: 3.7.1
.. method:: get([default])
Return a value for the context variable for the current context.
If there is no value for the variable in the current context,
the method will:
* return the value of the *default* argument of the method,
if provided; or
* return the default value for the context variable,
if it was created with one; or
* raise a :exc:`LookupError`.
.. method:: set(value)
Call to set a new value for the context variable in the current
context.
The required *value* argument is the new value for the context
variable.
Returns a :class:`~contextvars.Token` object that can be used
to restore the variable to its previous value via the
:meth:`ContextVar.reset` method.
.. method:: reset(token)
Reset the context variable to the value it had before the
:meth:`ContextVar.set` that created the *token* was used.
For example::
var = ContextVar('var')
token = var.set('new value')
# code that uses 'var'; var.get() returns 'new value'.
var.reset(token)
# After the reset call the var has no value again, so
# var.get() would raise a LookupError.
.. class:: Token
*Token* objects are returned by the :meth:`ContextVar.set` method.
They can be passed to the :meth:`ContextVar.reset` method to revert
the value of the variable to what it was before the corresponding
*set*.
.. attribute:: Token.var
A read-only property. Points to the :class:`ContextVar` object
that created the token.
.. attribute:: Token.old_value
A read-only property. Set to the value the variable had before
the :meth:`ContextVar.set` method call that created the token.
It points to :attr:`Token.MISSING` is the variable was not set
before the call.
.. attribute:: Token.MISSING
A marker object used by :attr:`Token.old_value`.
Manual Context Management
-------------------------
.. function:: copy_context()
Returns a copy of the current :class:`~contextvars.Context` object.
The following snippet gets a copy of the current context and prints
all variables and their values that are set in it::
ctx: Context = copy_context()
print(list(ctx.items()))
The function has an O(1) complexity, i.e. works equally fast for
contexts with a few context variables and for contexts that have
a lot of them.
.. class:: Context()
A mapping of :class:`ContextVars <ContextVar>` to their values.
``Context()`` creates an empty context with no values in it.
To get a copy of the current context use the
:func:`~contextvars.copy_context` function.
Context implements the :class:`collections.abc.Mapping` interface.
.. method:: run(callable, *args, **kwargs)
Execute ``callable(*args, **kwargs)`` code in the context object
the *run* method is called on. Return the result of the execution
or propagate an exception if one occurred.
Any changes to any context variables that *callable* makes will
be contained in the context object::
var = ContextVar('var')
var.set('spam')
def main():
# 'var' was set to 'spam' before
# calling 'copy_context()' and 'ctx.run(main)', so:
# var.get() == ctx[var] == 'spam'
var.set('ham')
# Now, after setting 'var' to 'ham':
# var.get() == ctx[var] == 'ham'
ctx = copy_context()
# Any changes that the 'main' function makes to 'var'
# will be contained in 'ctx'.
ctx.run(main)
# The 'main()' function was run in the 'ctx' context,
# so changes to 'var' are contained in it:
# ctx[var] == 'ham'
# However, outside of 'ctx', 'var' is still set to 'spam':
# var.get() == 'spam'
The method raises a :exc:`RuntimeError` when called on the same
context object from more than one OS thread, or when called
recursively.
.. method:: copy()
Return a shallow copy of the context object.
.. describe:: var in context
Return ``True`` if the *context* has a value for *var* set;
return ``False`` otherwise.
.. describe:: context[var]
Return the value of the *var* :class:`ContextVar` variable.
If the variable is not set in the context object, a
:exc:`KeyError` is raised.
.. method:: get(var, [default])
Return the value for *var* if *var* has the value in the context
object. Return *default* otherwise. If *default* is not given,
return ``None``.
.. describe:: iter(context)
Return an iterator over the variables stored in the context
object.
.. describe:: len(proxy)
Return the number of variables set in the context object.
.. method:: keys()
Return a list of all variables in the context object.
.. method:: values()
Return a list of all variables' values in the context object.
.. method:: items()
Return a list of 2-tuples containing all variables and their
values in the context object.
asyncio support
---------------
Context variables are natively supported in :mod:`asyncio` and are
ready to be used without any extra configuration. For example, here
is a simple echo server, that uses a context variable to make the
address of a remote client available in the Task that handles that
client::
import asyncio
import contextvars
client_addr_var = contextvars.ContextVar('client_addr')
def render_goodbye():
# The address of the currently handled client can be accessed
# without passing it explicitly to this function.
client_addr = client_addr_var.get()
return f'Good bye, client @ {client_addr}\n'.encode()
async def handle_request(reader, writer):
addr = writer.transport.get_extra_info('socket').getpeername()
client_addr_var.set(addr)
# In any code that we call is now possible to get
# client's address by calling 'client_addr_var.get()'.
while True:
line = await reader.readline()
print(line)
if not line.strip():
break
writer.write(line)
writer.write(render_goodbye())
writer.close()
async def main():
srv = await asyncio.start_server(
handle_request, '127.0.0.1', 8081)
async with srv:
await srv.serve_forever()
asyncio.run(main())
# To test it you can use telnet:
# telnet 127.0.0.1 8081

96
web/python-docs/_sources/library/copy.rst.txt Normal file
View File

@@ -0,0 +1,96 @@
:mod:`copy` --- Shallow and deep copy operations
================================================
.. module:: copy
:synopsis: Shallow and deep copy operations.
**Source code:** :source:`Lib/copy.py`
--------------
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[, memo])
Return a deep copy of *x*.
.. exception:: Error
Raised for module specific errors.
.. _shallow_vs_deep_copy:
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[:]``.
.. 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. In fact, the :mod:`copy` module uses the registered
pickle functions from the :mod:`copyreg` 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.

65
web/python-docs/_sources/library/copyreg.rst.txt Normal file
View File

@@ -0,0 +1,65 @@
:mod:`copyreg` --- Register :mod:`pickle` support functions
===========================================================
.. module:: copyreg
:synopsis: Register pickle support functions.
**Source code:** :source:`Lib/copyreg.py`
.. index::
module: pickle
module: copy
--------------
The :mod:`copyreg` module offers a way to define functions used while pickling
specific objects. The :mod:`pickle` 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=None)
Declares that *function* should be used as a "reduction" function for objects
of type *type*. *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*. Note that the
:attr:`~pickle.Pickler.dispatch_table` attribute of a pickler
object or subclass of :class:`pickle.Pickler` can also be used for
declaring reduction functions.
Example
-------
The example below would like to show how to register a pickle function and how
it will be used:
>>> import copyreg, 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,)
...
>>> copyreg.pickle(C, pickle_c)
>>> c = C(1)
>>> d = copy.copy(c) # doctest: +SKIP
pickling a C instance...
>>> p = pickle.dumps(c) # doctest: +SKIP
pickling a C instance...

175
web/python-docs/_sources/library/crypt.rst.txt Normal file
View File

@@ -0,0 +1,175 @@
: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>
**Source code:** :source:`Lib/crypt.py`
.. 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 storing hashed passwords
so you can check passwords without storing the actual password, 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.
.. availability:: Unix. Not available on VxWorks.
Hashing Methods
---------------
.. versionadded:: 3.3
The :mod:`crypt` module defines the list of hashing methods (not all methods
are available on all platforms):
.. data:: METHOD_SHA512
A Modular Crypt Format method with 16 character salt and 86 character
hash based on the SHA-512 hash function. This is the strongest method.
.. data:: METHOD_SHA256
Another Modular Crypt Format method with 16 character salt and 43
character hash based on the SHA-256 hash function.
.. data:: METHOD_BLOWFISH
Another Modular Crypt Format method with 22 character salt and 31
character hash based on the Blowfish cipher.
.. versionadded:: 3.7
.. data:: METHOD_MD5
Another Modular Crypt Format method with 8 character salt and 22
character hash based on the MD5 hash function.
.. data:: METHOD_CRYPT
The traditional method with a 2 character salt and 13 characters of
hash. This is the weakest method.
Module Attributes
-----------------
.. versionadded:: 3.3
.. attribute:: methods
A list of available password hashing algorithms, as
``crypt.METHOD_*`` objects. This list is sorted from strongest to
weakest.
Module Functions
----------------
The :mod:`crypt` module defines the following functions:
.. function:: crypt(word, salt=None)
*word* will usually be a user's password as typed at a prompt or in a graphical
interface. The optional *salt* is either a string as returned from
:func:`mksalt`, one of the ``crypt.METHOD_*`` values (though not all
may be available on all platforms), or a full encrypted password
including salt, as returned by this function. If *salt* is not
provided, the strongest method will be used (as returned by
:func:`methods`).
Checking a password is usually done by passing the plain-text password
as *word* and the full results of a previous :func:`crypt` call,
which should be the same as the results of this call.
*salt* (either a random 2 or 16 character string, possibly prefixed with
``$digit$`` to indicate the method) which will be used to perturb the
encryption algorithm. The characters in *salt* must be in the set
``[./a-zA-Z0-9]``, with the exception of Modular Crypt Format which
prefixes a ``$digit$``.
Returns the hashed password as a string, which will be composed of
characters from the same alphabet as the salt.
.. 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.
.. versionchanged:: 3.3
Accept ``crypt.METHOD_*`` values in addition to strings for *salt*.
.. function:: mksalt(method=None, *, rounds=None)
Return a randomly generated salt of the specified method. If no
*method* is given, the strongest method available as returned by
:func:`methods` is used.
The return value is a string suitable for passing as the *salt* argument
to :func:`crypt`.
*rounds* specifies the number of rounds for ``METHOD_SHA256``,
``METHOD_SHA512`` and ``METHOD_BLOWFISH``.
For ``METHOD_SHA256`` and ``METHOD_SHA512`` it must be an integer between
``1000`` and ``999_999_999``, the default is ``5000``. For
``METHOD_BLOWFISH`` it must be a power of two between ``16`` (2\ :sup:`4`)
and ``2_147_483_648`` (2\ :sup:`31`), the default is ``4096``
(2\ :sup:`12`).
.. versionadded:: 3.3
.. versionchanged:: 3.7
Added the *rounds* parameter.
Examples
--------
A simple example illustrating typical use (a constant-time comparison
operation is needed to limit exposure to timing attacks.
:func:`hmac.compare_digest` is suitable for this purpose)::
import pwd
import crypt
import getpass
from hmac import compare_digest as compare_hash
def login():
username = input('Python login: ')
cryptedpasswd = pwd.getpwnam(username)[1]
if cryptedpasswd:
if cryptedpasswd == 'x' or cryptedpasswd == '*':
raise ValueError('no support for shadow passwords')
cleartext = getpass.getpass()
return compare_hash(crypt.crypt(cleartext, cryptedpasswd), cryptedpasswd)
else:
return True
To generate a hash of a password using the strongest available method and
check it against the original::
import crypt
from hmac import compare_digest as compare_hash
hashed = crypt.crypt(plaintext)
if not compare_hash(hashed, crypt.crypt(plaintext, hashed)):
raise ValueError("hashed version doesn't validate against original")

19
web/python-docs/_sources/library/crypto.rst.txt Normal file
View File

@@ -0,0 +1,19 @@
.. _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.
On Unix systems, the :mod:`crypt` module may also be available.
Here's an overview:
.. toctree::
hashlib.rst
hmac.rst
secrets.rst

560
web/python-docs/_sources/library/csv.rst.txt Normal file
View File

@@ -0,0 +1,560 @@
: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>
**Source code:** :source:`Lib/csv.py`
.. 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. CSV format was used for many
years prior to attempts to describe the format in a standardized way in
:rfc:`4180`. The lack of a well-defined 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.
.. 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:
.. index::
single: universal newlines; csv.reader function
.. 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 --- :term:`file objects
<file object>` and list objects are both suitable. If *csvfile* is a file object,
it should be opened with ``newline=''``. [1]_ 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 unless the ``QUOTE_NONNUMERIC`` format
option is specified (in which case unquoted fields are transformed into floats).
A short usage example::
>>> import csv
>>> with open('eggs.csv', newline='') 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
.. 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 should be opened with
``newline=''`` [1]_. 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.
All other non-string data are stringified with :func:`str` before being written.
A short usage example::
import csv
with open('eggs.csv', 'w', newline='') 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. 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. This function returns an immutable
:class:`Dialect`.
.. 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.
The :mod:`csv` module defines the following classes:
.. class:: DictReader(f, fieldnames=None, restkey=None, restval=None, \
dialect='excel', *args, **kwds)
Create an object that operates like a regular reader but maps the
information in each row to a :class:`dict` whose keys are given by the
optional *fieldnames* parameter.
The *fieldnames* parameter is a :term:`sequence`. If *fieldnames* is
omitted, the values in the first row of file *f* will be used as the
fieldnames. Regardless of how the fieldnames are determined, the
dictionary preserves their original ordering.
If a row has more fields than fieldnames, the remaining data is put in a
list and stored with the fieldname specified by *restkey* (which defaults
to ``None``). If a non-blank row has fewer fields than fieldnames, the
missing values are filled-in with the value of *restval* (which defaults
to ``None``).
All other optional or keyword arguments are passed to the underlying
:class:`reader` instance.
.. versionchanged:: 3.6
Returned rows are now of type :class:`OrderedDict`.
.. versionchanged:: 3.8
Returned rows are now of type :class:`dict`.
A short usage example::
>>> import csv
>>> with open('names.csv', newline='') as csvfile:
... reader = csv.DictReader(csvfile)
... for row in reader:
... print(row['first_name'], row['last_name'])
...
Eric Idle
John Cleese
>>> print(row)
{'first_name': 'John', 'last_name': 'Cleese'}
.. 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 :mod:`sequence
<collections.abc>` of keys that identify the order in which values in the
dictionary passed to the :meth:`writerow` method are written to 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'``, the default value, 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` class is not optional.
A short usage example::
import csv
with open('names.csv', 'w', newline='') 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:: unix_dialect()
The :class:`unix_dialect` class defines the usual properties of a CSV file
generated on UNIX systems, i.e. using ``'\n'`` as line terminator and quoting
all fields. It is registered with the dialect name ``'unix'``.
.. versionadded:: 3.2
.. 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', newline='') 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 (if the object
was returned from :func:`reader`) or a dict (if it is a :class:`DictReader`
instance), parsed according to the current dialect. Usually you should call
this as ``next(reader)``.
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.
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.
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
an iterable 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. Return the return value of the call to the *write* method
of the underlying file object.
.. versionchanged:: 3.5
Added support of arbitrary iterables.
.. 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) to
the writer's file object, formatted according to the current dialect. Return
the return value of the :meth:`csvwriter.writerow` call used internally.
.. versionadded:: 3.2
.. versionchanged:: 3.8
:meth:`writeheader` now also returns the value returned by
the :meth:`csvwriter.writerow` method it uses internally.
.. _csv-examples:
Examples
--------
The simplest example of reading a CSV file::
import csv
with open('some.csv', newline='') as f:
reader = csv.reader(f)
for row in reader:
print(row)
Reading a file with an alternate format::
import csv
with open('passwd', newline='') 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', 'w', newline='') as f:
writer = csv.writer(f)
writer.writerows(someiterable)
Since :func:`open` is used to open a CSV file for reading, the file
will by default be decoded into unicode using the system default
encoding (see :func:`locale.getpreferredencoding`). To decode a file
using a different encoding, use the ``encoding`` argument of open::
import csv
with open('some.csv', newline='', encoding='utf-8') as f:
reader = csv.reader(f)
for row in reader:
print(row)
The same applies to writing in something other than the system default
encoding: specify the encoding argument when opening the output file.
Registering a new dialect::
import csv
csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)
with open('passwd', newline='') 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, newline='') as f:
reader = csv.reader(f)
try:
for row in reader:
print(row)
except csv.Error as e:
sys.exit('file {}, line {}: {}'.format(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)
.. rubric:: Footnotes
.. [1] If ``newline=''`` is not specified, newlines embedded inside quoted fields
will not be interpreted correctly, and on platforms that use ``\r\n`` linendings
on write an extra ``\r`` will be added. It should always be safe to specify
``newline=''``, since the csv module does its own
(:term:`universal <universal newlines>`) newline handling.

2562
web/python-docs/_sources/library/ctypes.rst.txt Normal file
View File

File diff suppressed because it is too large Load Diff

229
web/python-docs/_sources/library/curses.ascii.rst.txt Normal file
View File

@@ -0,0 +1,229 @@
: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>
--------------
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 single-character 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
character of the string you pass in; they do not actually know anything about
the host machine's character encoding.
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.
.. index::
single: ^ (caret); in curses module
single: ! (exclamation); in curses module
.. 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.

120
web/python-docs/_sources/library/curses.panel.rst.txt Normal file
View File

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

1857
web/python-docs/_sources/library/curses.rst.txt Normal file
View File

File diff suppressed because it is too large Load Diff

19
web/python-docs/_sources/library/custominterp.rst.txt Normal file
View File

@@ -0,0 +1,19 @@
.. _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

595
web/python-docs/_sources/library/dataclasses.rst.txt Normal file
View File

@@ -0,0 +1,595 @@
:mod:`dataclasses` --- Data Classes
===================================
.. module:: dataclasses
:synopsis: Generate special methods on user-defined classes.
.. moduleauthor:: Eric V. Smith <eric@trueblade.com>
.. sectionauthor:: Eric V. Smith <eric@trueblade.com>
**Source code:** :source:`Lib/dataclasses.py`
--------------
This module provides a decorator and functions for automatically
adding generated :term:`special method`\s such as :meth:`__init__` and
:meth:`__repr__` to user-defined classes. It was originally described
in :pep:`557`.
The member variables to use in these generated methods are defined
using :pep:`526` type annotations. For example this code::
from dataclasses import dataclass
@dataclass
class InventoryItem:
"""Class for keeping track of an item in inventory."""
name: str
unit_price: float
quantity_on_hand: int = 0
def total_cost(self) -> float:
return self.unit_price * self.quantity_on_hand
Will add, among other things, a :meth:`__init__` that looks like::
def __init__(self, name: str, unit_price: float, quantity_on_hand: int = 0):
self.name = name
self.unit_price = unit_price
self.quantity_on_hand = quantity_on_hand
Note that this method is automatically added to the class: it is not
directly specified in the ``InventoryItem`` definition shown above.
.. versionadded:: 3.7
Module-level decorators, classes, and functions
-----------------------------------------------
.. decorator:: dataclass(*, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False)
This function is a :term:`decorator` that is used to add generated
:term:`special method`\s to classes, as described below.
The :func:`dataclass` decorator examines the class to find
``field``\s. A ``field`` is defined as class variable that has a
:term:`type annotation <variable annotation>`. With two
exceptions described below, nothing in :func:`dataclass`
examines the type specified in the variable annotation.
The order of the fields in all of the generated methods is the
order in which they appear in the class definition.
The :func:`dataclass` decorator will add various "dunder" methods to
the class, described below. If any of the added methods already
exist on the class, the behavior depends on the parameter, as documented
below. The decorator returns the same class that is called on; no new
class is created.
If :func:`dataclass` is used just as a simple decorator with no parameters,
it acts as if it has the default values documented in this
signature. That is, these three uses of :func:`dataclass` are
equivalent::
@dataclass
class C:
...
@dataclass()
class C:
...
@dataclass(init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False)
class C:
...
The parameters to :func:`dataclass` are:
- ``init``: If true (the default), a :meth:`__init__` method will be
generated.
If the class already defines :meth:`__init__`, this parameter is
ignored.
- ``repr``: If true (the default), a :meth:`__repr__` method will be
generated. The generated repr string will have the class name and
the name and repr of each field, in the order they are defined in
the class. Fields that are marked as being excluded from the repr
are not included. For example:
``InventoryItem(name='widget', unit_price=3.0, quantity_on_hand=10)``.
If the class already defines :meth:`__repr__`, this parameter is
ignored.
- ``eq``: If true (the default), an :meth:`__eq__` method will be
generated. This method compares the class as if it were a tuple
of its fields, in order. Both instances in the comparison must
be of the identical type.
If the class already defines :meth:`__eq__`, this parameter is
ignored.
- ``order``: If true (the default is ``False``), :meth:`__lt__`,
:meth:`__le__`, :meth:`__gt__`, and :meth:`__ge__` methods will be
generated. These compare the class as if it were a tuple of its
fields, in order. Both instances in the comparison must be of the
identical type. If ``order`` is true and ``eq`` is false, a
:exc:`ValueError` is raised.
If the class already defines any of :meth:`__lt__`,
:meth:`__le__`, :meth:`__gt__`, or :meth:`__ge__`, then
:exc:`TypeError` is raised.
- ``unsafe_hash``: If ``False`` (the default), a :meth:`__hash__` method
is generated according to how ``eq`` and ``frozen`` are set.
:meth:`__hash__` is used by built-in :meth:`hash()`, and when objects are
added to hashed collections such as dictionaries and sets. Having a
:meth:`__hash__` implies that instances of the class are immutable.
Mutability is a complicated property that depends on the programmer's
intent, the existence and behavior of :meth:`__eq__`, and the values of
the ``eq`` and ``frozen`` flags in the :func:`dataclass` decorator.
By default, :func:`dataclass` will not implicitly add a :meth:`__hash__`
method unless it is safe to do so. Neither will it add or change an
existing explicitly defined :meth:`__hash__` method. Setting the class
attribute ``__hash__ = None`` has a specific meaning to Python, as
described in the :meth:`__hash__` documentation.
If :meth:`__hash__` is not explicitly defined, or if it is set to ``None``,
then :func:`dataclass` *may* add an implicit :meth:`__hash__` method.
Although not recommended, you can force :func:`dataclass` to create a
:meth:`__hash__` method with ``unsafe_hash=True``. This might be the case
if your class is logically immutable but can nonetheless be mutated.
This is a specialized use case and should be considered carefully.
Here are the rules governing implicit creation of a :meth:`__hash__`
method. Note that you cannot both have an explicit :meth:`__hash__`
method in your dataclass and set ``unsafe_hash=True``; this will result
in a :exc:`TypeError`.
If ``eq`` and ``frozen`` are both true, by default :func:`dataclass` will
generate a :meth:`__hash__` method for you. If ``eq`` is true and
``frozen`` is false, :meth:`__hash__` will be set to ``None``, marking it
unhashable (which it is, since it is mutable). If ``eq`` is false,
:meth:`__hash__` will be left untouched meaning the :meth:`__hash__`
method of the superclass will be used (if the superclass is
:class:`object`, this means it will fall back to id-based hashing).
- ``frozen``: If true (the default is ``False``), assigning to fields will
generate an exception. This emulates read-only frozen instances. If
:meth:`__setattr__` or :meth:`__delattr__` is defined in the class, then
:exc:`TypeError` is raised. See the discussion below.
``field``\s may optionally specify a default value, using normal
Python syntax::
@dataclass
class C:
a: int # 'a' has no default value
b: int = 0 # assign a default value for 'b'
In this example, both ``a`` and ``b`` will be included in the added
:meth:`__init__` method, which will be defined as::
def __init__(self, a: int, b: int = 0):
:exc:`TypeError` will be raised if a field without a default value
follows a field with a default value. This is true either when this
occurs in a single class, or as a result of class inheritance.
.. function:: field(*, default=MISSING, default_factory=MISSING, repr=True, hash=None, init=True, compare=True, metadata=None)
For common and simple use cases, no other functionality is
required. There are, however, some dataclass features that
require additional per-field information. To satisfy this need for
additional information, you can replace the default field value
with a call to the provided :func:`field` function. For example::
@dataclass
class C:
mylist: List[int] = field(default_factory=list)
c = C()
c.mylist += [1, 2, 3]
As shown above, the ``MISSING`` value is a sentinel object used to
detect if the ``default`` and ``default_factory`` parameters are
provided. This sentinel is used because ``None`` is a valid value
for ``default``. No code should directly use the ``MISSING``
value.
The parameters to :func:`field` are:
- ``default``: If provided, this will be the default value for this
field. This is needed because the :meth:`field` call itself
replaces the normal position of the default value.
- ``default_factory``: If provided, it must be a zero-argument
callable that will be called when a default value is needed for
this field. Among other purposes, this can be used to specify
fields with mutable default values, as discussed below. It is an
error to specify both ``default`` and ``default_factory``.
- ``init``: If true (the default), this field is included as a
parameter to the generated :meth:`__init__` method.
- ``repr``: If true (the default), this field is included in the
string returned by the generated :meth:`__repr__` method.
- ``compare``: If true (the default), this field is included in the
generated equality and comparison methods (:meth:`__eq__`,
:meth:`__gt__`, et al.).
- ``hash``: This can be a bool or ``None``. If true, this field is
included in the generated :meth:`__hash__` method. If ``None`` (the
default), use the value of ``compare``: this would normally be
the expected behavior. A field should be considered in the hash
if it's used for comparisons. Setting this value to anything
other than ``None`` is discouraged.
One possible reason to set ``hash=False`` but ``compare=True``
would be if a field is expensive to compute a hash value for,
that field is needed for equality testing, and there are other
fields that contribute to the type's hash value. Even if a field
is excluded from the hash, it will still be used for comparisons.
- ``metadata``: This can be a mapping or None. None is treated as
an empty dict. This value is wrapped in
:func:`~types.MappingProxyType` to make it read-only, and exposed
on the :class:`Field` object. It is not used at all by Data
Classes, and is provided as a third-party extension mechanism.
Multiple third-parties can each have their own key, to use as a
namespace in the metadata.
If the default value of a field is specified by a call to
:func:`field()`, then the class attribute for this field will be
replaced by the specified ``default`` value. If no ``default`` is
provided, then the class attribute will be deleted. The intent is
that after the :func:`dataclass` decorator runs, the class
attributes will all contain the default values for the fields, just
as if the default value itself were specified. For example,
after::
@dataclass
class C:
x: int
y: int = field(repr=False)
z: int = field(repr=False, default=10)
t: int = 20
The class attribute ``C.z`` will be ``10``, the class attribute
``C.t`` will be ``20``, and the class attributes ``C.x`` and
``C.y`` will not be set.
.. class:: Field
:class:`Field` objects describe each defined field. These objects
are created internally, and are returned by the :func:`fields`
module-level method (see below). Users should never instantiate a
:class:`Field` object directly. Its documented attributes are:
- ``name``: The name of the field.
- ``type``: The type of the field.
- ``default``, ``default_factory``, ``init``, ``repr``, ``hash``,
``compare``, and ``metadata`` have the identical meaning and
values as they do in the :func:`field` declaration.
Other attributes may exist, but they are private and must not be
inspected or relied on.
.. function:: fields(class_or_instance)
Returns a tuple of :class:`Field` objects that define the fields for this
dataclass. Accepts either a dataclass, or an instance of a dataclass.
Raises :exc:`TypeError` if not passed a dataclass or instance of one.
Does not return pseudo-fields which are ``ClassVar`` or ``InitVar``.
.. function:: asdict(instance, *, dict_factory=dict)
Converts the dataclass ``instance`` to a dict (by using the
factory function ``dict_factory``). Each dataclass is converted
to a dict of its fields, as ``name: value`` pairs. dataclasses, dicts,
lists, and tuples are recursed into. For example::
@dataclass
class Point:
x: int
y: int
@dataclass
class C:
mylist: List[Point]
p = Point(10, 20)
assert asdict(p) == {'x': 10, 'y': 20}
c = C([Point(0, 0), Point(10, 4)])
assert asdict(c) == {'mylist': [{'x': 0, 'y': 0}, {'x': 10, 'y': 4}]}
Raises :exc:`TypeError` if ``instance`` is not a dataclass instance.
.. function:: astuple(instance, *, tuple_factory=tuple)
Converts the dataclass ``instance`` to a tuple (by using the
factory function ``tuple_factory``). Each dataclass is converted
to a tuple of its field values. dataclasses, dicts, lists, and
tuples are recursed into.
Continuing from the previous example::
assert astuple(p) == (10, 20)
assert astuple(c) == ([(0, 0), (10, 4)],)
Raises :exc:`TypeError` if ``instance`` is not a dataclass instance.
.. function:: make_dataclass(cls_name, fields, *, bases=(), namespace=None, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False)
Creates a new dataclass with name ``cls_name``, fields as defined
in ``fields``, base classes as given in ``bases``, and initialized
with a namespace as given in ``namespace``. ``fields`` is an
iterable whose elements are each either ``name``, ``(name, type)``,
or ``(name, type, Field)``. If just ``name`` is supplied,
``typing.Any`` is used for ``type``. The values of ``init``,
``repr``, ``eq``, ``order``, ``unsafe_hash``, and ``frozen`` have
the same meaning as they do in :func:`dataclass`.
This function is not strictly required, because any Python
mechanism for creating a new class with ``__annotations__`` can
then apply the :func:`dataclass` function to convert that class to
a dataclass. This function is provided as a convenience. For
example::
C = make_dataclass('C',
[('x', int),
'y',
('z', int, field(default=5))],
namespace={'add_one': lambda self: self.x + 1})
Is equivalent to::
@dataclass
class C:
x: int
y: 'typing.Any'
z: int = 5
def add_one(self):
return self.x + 1
.. function:: replace(instance, **changes)
Creates a new object of the same type of ``instance``, replacing
fields with values from ``changes``. If ``instance`` is not a Data
Class, raises :exc:`TypeError`. If values in ``changes`` do not
specify fields, raises :exc:`TypeError`.
The newly returned object is created by calling the :meth:`__init__`
method of the dataclass. This ensures that
:meth:`__post_init__`, if present, is also called.
Init-only variables without default values, if any exist, must be
specified on the call to :func:`replace` so that they can be passed to
:meth:`__init__` and :meth:`__post_init__`.
It is an error for ``changes`` to contain any fields that are
defined as having ``init=False``. A :exc:`ValueError` will be raised
in this case.
Be forewarned about how ``init=False`` fields work during a call to
:func:`replace`. They are not copied from the source object, but
rather are initialized in :meth:`__post_init__`, if they're
initialized at all. It is expected that ``init=False`` fields will
be rarely and judiciously used. If they are used, it might be wise
to have alternate class constructors, or perhaps a custom
``replace()`` (or similarly named) method which handles instance
copying.
.. function:: is_dataclass(class_or_instance)
Return ``True`` if its parameter is a dataclass or an instance of one,
otherwise return ``False``.
If you need to know if a class is an instance of a dataclass (and
not a dataclass itself), then add a further check for ``not
isinstance(obj, type)``::
def is_dataclass_instance(obj):
return is_dataclass(obj) and not isinstance(obj, type)
Post-init processing
--------------------
The generated :meth:`__init__` code will call a method named
:meth:`__post_init__`, if :meth:`__post_init__` is defined on the
class. It will normally be called as ``self.__post_init__()``.
However, if any ``InitVar`` fields are defined, they will also be
passed to :meth:`__post_init__` in the order they were defined in the
class. If no :meth:`__init__` method is generated, then
:meth:`__post_init__` will not automatically be called.
Among other uses, this allows for initializing field values that
depend on one or more other fields. For example::
@dataclass
class C:
a: float
b: float
c: float = field(init=False)
def __post_init__(self):
self.c = self.a + self.b
See the section below on init-only variables for ways to pass
parameters to :meth:`__post_init__`. Also see the warning about how
:func:`replace` handles ``init=False`` fields.
Class variables
---------------
One of two places where :func:`dataclass` actually inspects the type
of a field is to determine if a field is a class variable as defined
in :pep:`526`. It does this by checking if the type of the field is
``typing.ClassVar``. If a field is a ``ClassVar``, it is excluded
from consideration as a field and is ignored by the dataclass
mechanisms. Such ``ClassVar`` pseudo-fields are not returned by the
module-level :func:`fields` function.
Init-only variables
-------------------
The other place where :func:`dataclass` inspects a type annotation is to
determine if a field is an init-only variable. It does this by seeing
if the type of a field is of type ``dataclasses.InitVar``. If a field
is an ``InitVar``, it is considered a pseudo-field called an init-only
field. As it is not a true field, it is not returned by the
module-level :func:`fields` function. Init-only fields are added as
parameters to the generated :meth:`__init__` method, and are passed to
the optional :meth:`__post_init__` method. They are not otherwise used
by dataclasses.
For example, suppose a field will be initialized from a database, if a
value is not provided when creating the class::
@dataclass
class C:
i: int
j: int = None
database: InitVar[DatabaseType] = None
def __post_init__(self, database):
if self.j is None and database is not None:
self.j = database.lookup('j')
c = C(10, database=my_database)
In this case, :func:`fields` will return :class:`Field` objects for ``i`` and
``j``, but not for ``database``.
Frozen instances
----------------
It is not possible to create truly immutable Python objects. However,
by passing ``frozen=True`` to the :meth:`dataclass` decorator you can
emulate immutability. In that case, dataclasses will add
:meth:`__setattr__` and :meth:`__delattr__` methods to the class. These
methods will raise a :exc:`FrozenInstanceError` when invoked.
There is a tiny performance penalty when using ``frozen=True``:
:meth:`__init__` cannot use simple assignment to initialize fields, and
must use :meth:`object.__setattr__`.
Inheritance
-----------
When the dataclass is being created by the :meth:`dataclass` decorator,
it looks through all of the class's base classes in reverse MRO (that
is, starting at :class:`object`) and, for each dataclass that it finds,
adds the fields from that base class to an ordered mapping of fields.
After all of the base class fields are added, it adds its own fields
to the ordered mapping. All of the generated methods will use this
combined, calculated ordered mapping of fields. Because the fields
are in insertion order, derived classes override base classes. An
example::
@dataclass
class Base:
x: Any = 15.0
y: int = 0
@dataclass
class C(Base):
z: int = 10
x: int = 15
The final list of fields is, in order, ``x``, ``y``, ``z``. The final
type of ``x`` is ``int``, as specified in class ``C``.
The generated :meth:`__init__` method for ``C`` will look like::
def __init__(self, x: int = 15, y: int = 0, z: int = 10):
Default factory functions
-------------------------
If a :func:`field` specifies a ``default_factory``, it is called with
zero arguments when a default value for the field is needed. For
example, to create a new instance of a list, use::
mylist: list = field(default_factory=list)
If a field is excluded from :meth:`__init__` (using ``init=False``)
and the field also specifies ``default_factory``, then the default
factory function will always be called from the generated
:meth:`__init__` function. This happens because there is no other
way to give the field an initial value.
Mutable default values
----------------------
Python stores default member variable values in class attributes.
Consider this example, not using dataclasses::
class C:
x = []
def add(self, element):
self.x.append(element)
o1 = C()
o2 = C()
o1.add(1)
o2.add(2)
assert o1.x == [1, 2]
assert o1.x is o2.x
Note that the two instances of class ``C`` share the same class
variable ``x``, as expected.
Using dataclasses, *if* this code was valid::
@dataclass
class D:
x: List = []
def add(self, element):
self.x += element
it would generate code similar to::
class D:
x = []
def __init__(self, x=x):
self.x = x
def add(self, element):
self.x += element
assert D().x is D().x
This has the same issue as the original example using class ``C``.
That is, two instances of class ``D`` that do not specify a value for
``x`` when creating a class instance will share the same copy of
``x``. Because dataclasses just use normal Python class creation
they also share this behavior. There is no general way for Data
Classes to detect this condition. Instead, dataclasses will raise a
:exc:`TypeError` if it detects a default parameter of type ``list``,
``dict``, or ``set``. This is a partial solution, but it does protect
against many common errors.
Using default factory functions is a way to create new instances of
mutable types as default values for fields::
@dataclass
class D:
x: list = field(default_factory=list)
assert D().x is not D().x
Exceptions
----------
.. exception:: FrozenInstanceError
Raised when an implicitly defined :meth:`__setattr__` or
:meth:`__delattr__` is called on a dataclass which was defined with
``frozen=True``. It is a subclass of :exc:`AttributeError`.

34
web/python-docs/_sources/library/datatypes.rst.txt Normal file
View File

@@ -0,0 +1,34 @@
.. _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, double-ended
queues, and enumerations.
Python also provides some built-in data types, in particular,
:class:`dict`, :class:`list`, :class:`set` and :class:`frozenset`, and
:class:`tuple`. The :class:`str` class is used to hold
Unicode strings, and the :class:`bytes` and :class:`bytearray` classes are used
to hold binary data.
The following modules are documented in this chapter:
.. toctree::
datetime.rst
calendar.rst
collections.rst
collections.abc.rst
heapq.rst
bisect.rst
array.rst
weakref.rst
types.rst
copy.rst
pprint.rst
reprlib.rst
enum.rst

2574
web/python-docs/_sources/library/datetime.rst.txt Normal file
View File

File diff suppressed because it is too large Load Diff

394
web/python-docs/_sources/library/dbm.rst.txt Normal file
View File

@@ -0,0 +1,394 @@
:mod:`dbm` --- Interfaces to Unix "databases"
=============================================
.. module:: dbm
:synopsis: Interfaces to various Unix "database" formats.
**Source code:** :source:`Lib/dbm/__init__.py`
--------------
:mod:`dbm` is a generic interface to variants of the DBM database ---
:mod:`dbm.gnu` or :mod:`dbm.ndbm`. If none of these modules is installed, the
slow-but-simple implementation in module :mod:`dbm.dumb` will be used. There
is a `third party interface <https://www.jcea.es/programacion/pybsddb.htm>`_ to
the Oracle Berkeley DB.
.. exception:: error
A tuple containing the exceptions that can be raised by each of the supported
modules, with a unique exception also named :exc:`dbm.error` as the first
item --- the latter is used when :exc:`dbm.error` is raised.
.. function:: whichdb(filename)
This function attempts to guess which of the several simple database modules
available --- :mod:`dbm.gnu`, :mod:`dbm.ndbm` or :mod:`dbm.dumb` --- should
be used to open a given file.
Returns one of the following values: ``None`` if the file can't be opened
because it's unreadable or doesn't exist; the empty string (``''``) if the
file's format can't be guessed; or a string containing the required module
name, such as ``'dbm.ndbm'`` or ``'dbm.gnu'``.
.. function:: open(file, flag='r', mode=0o666)
Open the database file *file* and return a corresponding object.
If the database file already exists, the :func:`whichdb` function is used to
determine its type and the appropriate module is used; if it does not exist,
the first module listed above that can be imported is used.
The optional *flag* argument can be:
+---------+-------------------------------------------+
| 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 ``0o666`` (and will be
modified by the prevailing umask).
The object returned by :func:`.open` supports the same basic functionality as
dictionaries; keys and their corresponding values can be stored, retrieved, and
deleted, and the :keyword:`in` operator and the :meth:`keys` method are
available, as well as :meth:`get` and :meth:`setdefault`.
.. versionchanged:: 3.2
:meth:`get` and :meth:`setdefault` are now available in all database modules.
.. versionchanged:: 3.8
Deleting a key from a read-only database raises database module specific error
instead of :exc:`KeyError`.
Key and values are always stored as bytes. This means that when
strings are used they are implicitly converted to the default encoding before
being stored.
These objects also support being used in a :keyword:`with` statement, which
will automatically close them when done.
.. versionchanged:: 3.4
Added native support for the context management protocol to the objects
returned by :func:`.open`.
The following example records some hostnames and a corresponding title, and
then prints out the contents of the database::
import dbm
# Open database, creating it if necessary.
with dbm.open('cache', 'c') as db:
# Record some values
db[b'hello'] = b'there'
db['www.python.org'] = 'Python Website'
db['www.cnn.com'] = 'Cable News Network'
# Note that the keys are considered bytes now.
assert db[b'www.python.org'] == b'Python Website'
# Notice how the value is now in bytes.
assert db['www.cnn.com'] == b'Cable News Network'
# Often-used methods of the dict interface work too.
print(db.get('python.org', b'not present'))
# Storing a non-string key or value will raise an exception (most
# likely a TypeError).
db['www.yahoo.com'] = 4
# db is automatically closed when leaving the with statement.
.. seealso::
Module :mod:`shelve`
Persistence module which stores non-string data.
The individual submodules are described in the following sections.
:mod:`dbm.gnu` --- GNU's reinterpretation of dbm
------------------------------------------------
.. module:: dbm.gnu
:platform: Unix
:synopsis: GNU's reinterpretation of dbm.
**Source code:** :source:`Lib/dbm/gnu.py`
--------------
This module is quite similar to the :mod:`dbm` module, but uses the GNU library
``gdbm`` instead to provide some additional functionality. Please note that the
file formats created by :mod:`dbm.gnu` and :mod:`dbm.ndbm` are incompatible.
The :mod:`dbm.gnu` module provides an interface to the GNU DBM library.
``dbm.gnu.gdbm`` objects behave like mappings (dictionaries), except that keys and
values are always converted to bytes before storing. Printing a ``gdbm``
object doesn't print the
keys and values, and the :meth:`items` and :meth:`values` methods are not
supported.
.. exception:: error
Raised on :mod:`dbm.gnu`-specific errors, such as I/O errors. :exc:`KeyError` is
raised for general mapping errors like specifying an incorrect key.
.. function:: open(filename[, flag[, mode]])
Open a ``gdbm`` database and return a :class:`gdbm` object. The *filename*
argument is the name of the database file.
The optional *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 |
+---------+-------------------------------------------+
The following additional characters may be appended to the flag to control
how the database is opened:
+---------+--------------------------------------------+
| Value | Meaning |
+=========+============================================+
| ``'f'`` | Open the database in fast mode. Writes |
| | to the database will not be synchronized. |
+---------+--------------------------------------------+
| ``'s'`` | Synchronized mode. This will cause changes |
| | to the database to be immediately written |
| | to the file. |
+---------+--------------------------------------------+
| ``'u'`` | Do not lock database. |
+---------+--------------------------------------------+
Not all flags are valid for all versions of ``gdbm``. The module constant
:const:`open_flags` is a string of supported flag characters. The exception
:exc:`error` is raised if an invalid flag is specified.
The optional *mode* argument is the Unix mode of the file, used only when the
database has to be created. It defaults to octal ``0o666``.
In addition to the dictionary-like methods, ``gdbm`` objects have the
following methods:
.. method:: gdbm.firstkey()
It's possible to loop over every key in the database using this method and the
:meth:`nextkey` method. The traversal is ordered by ``gdbm``'s internal
hash values, and won't be sorted by the key values. This method returns
the starting key.
.. method:: gdbm.nextkey(key)
Returns the key that follows *key* in the traversal. The following code prints
every key in the database ``db``, without having to create a list in memory that
contains them all::
k = db.firstkey()
while k != None:
print(k)
k = db.nextkey(k)
.. method:: gdbm.reorganize()
If you have carried out a lot of deletions and would like to shrink the space
used by the ``gdbm`` file, this routine will reorganize the database. ``gdbm``
objects will not shorten the length of a database file except by using this
reorganization; otherwise, deleted file space will be kept and reused as new
(key, value) pairs are added.
.. method:: gdbm.sync()
When the database has been opened in fast mode, this method forces any
unwritten data to be written to the disk.
.. method:: gdbm.close()
Close the ``gdbm`` database.
:mod:`dbm.ndbm` --- Interface based on ndbm
-------------------------------------------
.. module:: dbm.ndbm
:platform: Unix
:synopsis: The standard "database" interface, based on ndbm.
**Source code:** :source:`Lib/dbm/ndbm.py`
--------------
The :mod:`dbm.ndbm` module provides an interface to the Unix "(n)dbm" library.
Dbm objects behave like mappings (dictionaries), except that keys and values are
always stored as bytes. 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 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.
.. exception:: error
Raised on :mod:`dbm.ndbm`-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 ``ndbm`` object. The *filename* argument is the
name of the database file (without the :file:`.dir` or :file:`.pag` extensions).
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 ``0o666`` (and will be
modified by the prevailing umask).
In addition to the dictionary-like methods, ``ndbm`` objects
provide the following method:
.. method:: ndbm.close()
Close the ``ndbm`` database.
:mod:`dbm.dumb` --- Portable DBM implementation
-----------------------------------------------
.. module:: dbm.dumb
:synopsis: Portable implementation of the simple DBM interface.
**Source code:** :source:`Lib/dbm/dumb.py`
.. index:: single: databases
.. note::
The :mod:`dbm.dumb` module is intended as a last resort fallback for the
:mod:`dbm` module when a more robust module is not available. The :mod:`dbm.dumb`
module is not written for speed and is not nearly as heavily used as the other
database modules.
--------------
The :mod:`dbm.dumb` module provides a persistent dictionary-like interface which
is written entirely in Python. Unlike other modules such as :mod:`dbm.gnu` no
external library is required. As with other persistent mappings, the keys and
values are always stored as bytes.
The module defines the following:
.. exception:: error
Raised on :mod:`dbm.dumb`-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 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 |
+---------+-------------------------------------------+
The optional *mode* argument is the Unix mode of the file, used only when the
database has to be created. It defaults to octal ``0o666`` (and will be modified
by the prevailing umask).
.. warning::
It is possible to crash the Python interpreter when loading a database
with a sufficiently large/complex entry due to stack depth limitations in
Python's AST compiler.
.. versionchanged:: 3.5
:func:`.open` always creates a new database when the flag has the value
``'n'``.
.. versionchanged:: 3.8
A database opened with flags ``'r'`` is now read-only. Opening with
flags ``'r'`` and ``'w'`` no longer creates a database if it does not
exist.
In addition to the methods provided by the
:class:`collections.abc.MutableMapping` class, :class:`dumbdbm` objects
provide the following methods:
.. method:: dumbdbm.sync()
Synchronize the on-disk directory and data files. This method is called
by the :meth:`Shelve.sync` method.
.. method:: dumbdbm.close()
Close the ``dumbdbm`` database.

21
web/python-docs/_sources/library/debug.rst.txt Normal file
View File

@@ -0,0 +1,21 @@
***********************
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. Auditing events
provide visibility into runtime behaviors that would otherwise require
intrusive debugging or patching.
.. toctree::
audit_events.rst
bdb.rst
faulthandler.rst
pdb.rst
profile.rst
timeit.rst
trace.rst
tracemalloc.rst

2149
web/python-docs/_sources/library/decimal.rst.txt Normal file
View File

File diff suppressed because it is too large Load Diff

29
web/python-docs/_sources/library/development.rst.txt Normal file
View File

@@ -0,0 +1,29 @@
.. _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::
typing.rst
pydoc.rst
doctest.rst
unittest.rst
unittest.mock.rst
unittest.mock-examples.rst
2to3.rst
test.rst
See also the Python development mode: the :option:`-X` ``dev`` option and
:envvar:`PYTHONDEVMODE` environment variable.

762
web/python-docs/_sources/library/difflib.rst.txt Normal file
View File

@@ -0,0 +1,762 @@
: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>
**Source code:** :source:`Lib/difflib.py`
.. testsetup::
import sys
from difflib import *
--------------
This module provides classes and functions for comparing sequences. It
can be used for example, for comparing files, and can produce information
about file differences in various formats, including HTML and context and unified
diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
.. class:: SequenceMatcher
:noindex:
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; these "junk" elements are ones that are uninteresting in some
sense, such as blank lines or whitespace. (Handling junk is an
extension to the Ratcliff and Obershelp algorithm.) 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:: 3.2
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:
.. method:: __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:
.. method:: make_file(fromlines, tolines, fromdesc='', todesc='', context=False, \
numlines=5, *, charset='utf-8')
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).
.. note::
*fromdesc* and *todesc* are interpreted as unescaped HTML and should be
properly escaped while receiving input from untrusted sources.
.. versionchanged:: 3.5
*charset* keyword-only argument was added. The default charset of
HTML document changed from ``'ISO-8859-1'`` to ``'utf-8'``.
.. method:: make_table(fromlines, tolines, fromdesc='', todesc='', context=False, numlines=5)
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.
.. function:: context_diff(a, b, fromfile='', tofile='', fromfiledate='', tofiledate='', n=3, lineterm='\\n')
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:`io.IOBase.readlines` result in diffs that are suitable for use with
:func:`io.IOBase.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']
>>> sys.stdout.writelines(context_diff(s1, s2, fromfile='before.py', tofile='after.py'))
*** 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.
.. function:: get_close_matches(word, possibilities, n=3, cutoff=0.6)
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('pineapple', keyword.kwlist)
[]
>>> get_close_matches('accept', keyword.kwlist)
['except']
.. function:: ndiff(a, b, linejunk=None, charjunk=IS_CHARACTER_JUNK)
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 filtering 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``. There
is also a module-level function :func:`IS_LINE_JUNK`, which filters out lines
without visible characters, except for at most one pound character (``'#'``)
-- however 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 using this function.
*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; it's a 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(keepends=True),
... 'ore\ntree\nemu\n'.splitlines(keepends=True))
>>> print(''.join(diff), end="")
- 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(keepends=True),
... 'ore\ntree\nemu\n'.splitlines(keepends=True))
>>> diff = list(diff) # materialize the generated delta into a list
>>> print(''.join(restore(diff, 1)), end="")
one
two
three
>>> print(''.join(restore(diff, 2)), end="")
ore
tree
emu
.. function:: unified_diff(a, b, fromfile='', tofile='', fromfiledate='', tofiledate='', n=3, lineterm='\\n')
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:`io.IOBase.readlines` result in diffs that are suitable for use with
:func:`io.IOBase.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']
>>> sys.stdout.writelines(unified_diff(s1, s2, fromfile='before.py', tofile='after.py'))
--- before.py
+++ after.py
@@ -1,4 +1,4 @@
-bacon
-eggs
-ham
+python
+eggy
+hamster
guido
See :ref:`difflib-interface` for a more detailed example.
.. function:: diff_bytes(dfunc, a, b, fromfile=b'', tofile=b'', fromfiledate=b'', tofiledate=b'', n=3, lineterm=b'\\n')
Compare *a* and *b* (lists of bytes objects) using *dfunc*; yield a
sequence of delta lines (also bytes) in the format returned by *dfunc*.
*dfunc* must be a callable, typically either :func:`unified_diff` or
:func:`context_diff`.
Allows you to compare data with unknown or inconsistent encoding. All
inputs except *n* must be bytes objects, not str. Works by losslessly
converting all inputs (except *n*) to str, and calling ``dfunc(a, b,
fromfile, tofile, fromfiledate, tofiledate, n, lineterm)``. The output of
*dfunc* is then converted back to bytes, so the delta lines that you
receive have the same unknown/inconsistent encodings as *a* and *b*.
.. versionadded:: 3.5
.. 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` in older versions.
.. 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: False``; 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:: 3.2
The *autojunk* parameter.
SequenceMatcher objects get three data attributes: *bjunk* is the
set of elements of *b* for which *isjunk* is ``True``; *bpopular* is the set of
non-junk elements considered popular by the heuristic (if it is not
disabled); *b2j* is a dict mapping the remaining elements of *b* to a list
of positions where they occur. All three are reset whenever *b* is reset
with :meth:`set_seqs` or :meth:`set_seq2`.
.. versionadded:: 3.2
The *bjunk* and *bpopular* attributes.
: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)``.
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!
.. 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('{:7} a[{}:{}] --> b[{}:{}] {!r:>8} --> {!r}'.format(
... tag, i1, i2, j1, j2, a[i1:i2], b[j1:j2]))
delete a[0:1] --> b[0:0] 'q' --> ''
equal a[1:3] --> b[0:2] 'ab' --> 'ab'
replace a[3:4] --> b[2:3] 'x' --> 'y'
equal a[4:6] --> b[3:5] 'cd' --> 'cd'
insert a[6:6] --> b[5:6] '' --> 'f'
.. method:: get_grouped_opcodes(n=3)
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`.
.. 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.
.. note::
Caution: The result of a :meth:`ratio` call may depend on the order of
the arguments. For instance::
>>> SequenceMatcher(None, 'tide', 'diet').ratio()
0.25
>>> SequenceMatcher(None, 'diet', 'tide').ratio()
0.5
.. 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=None, charjunk=None)
:noindex:
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.
These junk-filtering functions speed up matching to find
differences and do not cause any differing lines or characters to
be ignored. Read the description of the
:meth:`~SequenceMatcher.find_longest_match` method's *isjunk*
parameter for an explanation.
: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:`~io.IOBase.readlines` method of file-like objects. The delta
generated also consists of newline-terminated strings, ready to be
printed as-is via the :meth:`~io.IOBase.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:`~io.BaseIO.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(keepends=True)
>>> 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(keepends=True)
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`.
.. literalinclude:: ../../Tools/scripts/diff.py

1323
web/python-docs/_sources/library/dis.rst.txt Normal file
View File

File diff suppressed because it is too large Load Diff

15
web/python-docs/_sources/library/distribution.rst.txt Normal file
View File

@@ -0,0 +1,15 @@
***********************************
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
venv.rst
zipapp.rst

44
web/python-docs/_sources/library/distutils.rst.txt Normal file
View File

@@ -0,0 +1,44 @@
: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`

1866
web/python-docs/_sources/library/doctest.rst.txt Normal file
View File

File diff suppressed because it is too large Load Diff

20
web/python-docs/_sources/library/dummy_threading.rst.txt Normal file
View File

@@ -0,0 +1,20 @@
: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`
.. deprecated:: 3.7
Python now always has threading enabled. Please use :mod:`threading` instead.
--------------
This module provides a duplicate interface to the :mod:`threading` module.
It was meant to be imported when the :mod:`_thread` module was not provided
on a platform.
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.

214
web/python-docs/_sources/library/email.charset.rst.txt Normal file
View File

@@ -0,0 +1,214 @@
:mod:`email.charset`: Representing character sets
-------------------------------------------------
.. module:: email.charset
:synopsis: Character Sets
**Source code:** :source:`Lib/email/charset.py`
--------------
This module is part of the legacy (``Compat32``) email API. In the new
API only the aliases table is used.
The remaining text in this section is the original documentation of the module.
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.
.. class:: Charset(input_charset=DEFAULT_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:: 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:: header_encode(string)
Header-encode the string *string*.
The type of encoding (base64 or quoted-printable) will be based on the
*header_encoding* attribute.
.. method:: header_encode_lines(string, maxlengths)
Header-encode a *string* by converting it first to bytes.
This is similar to :meth:`header_encode` except that the string is fit
into maximum line lengths as given by the argument *maxlengths*, which
must be an iterator: each element returned from this iterator will provide
the next maximum line length.
.. method:: body_encode(string)
Body-encode the string *string*.
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=None, body_enc=None, output_charset=None)
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 :class:`str`'s
:meth:`~str.encode` method.

759
web/python-docs/_sources/library/email.compat32-message.rst.txt Normal file
View File

@@ -0,0 +1,759 @@
.. _compat32_message:
:mod:`email.message.Message`: Representing an email message using the :data:`~email.policy.compat32` API
--------------------------------------------------------------------------------------------------------
.. module:: email.message
:synopsis: The base class representing email messages in a fashion
backward compatible with Python 3.2
:noindex:
The :class:`Message` class is very similar to the
:class:`~email.message.EmailMessage` class, without the methods added by that
class, and with the default behavior of certain other methods being slightly
different. We also document here some methods that, while supported by the
:class:`~email.message.EmailMessage` class, are not recommended unless you are
dealing with legacy code.
The philosophy and structure of the two classes is otherwise the same.
This document describes the behavior under the default (for :class:`Message`)
policy :attr:`~email.policy.Compat32`. If you are going to use another policy,
you should be using the :class:`~email.message.EmailMessage` class instead.
An email message consists of *headers* and a *payload*. Headers must be
:rfc:`5322` style 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. The payload may be a simple text message, or a binary object, or
a structured sequence of sub-messages each with their own set of headers and
their own payload. The latter type of payload is indicated by the message
having a MIME type such as :mimetype:`multipart/\*` or
:mimetype:`message/rfc822`.
The conceptual model provided by a :class:`Message` object is that of an
ordered dictionary of headers with additional methods for accessing both
specialized information from the headers, for accessing the payload, for
generating a serialized version of the message, and for recursively walking
over the object tree. Note that duplicate headers are supported but special
methods must be used to access them.
The :class:`Message` pseudo-dictionary is indexed by the header names, which
must be ASCII values. The values of the dictionary are strings that are
supposed to contain only ASCII characters; there is some special handling for
non-ASCII input, but it doesn't always produce the correct results. Headers
are stored and returned in case-preserving form, but field names 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 or bytes, 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`).
Here are the methods of the :class:`Message` class:
.. class:: Message(policy=compat32)
If *policy* is specified (it must be an instance of a :mod:`~email.policy`
class) use the rules it specifies to update and serialize the representation
of the message. If *policy* is not set, use the :class:`compat32
<email.policy.Compat32>` policy, which maintains backward compatibility with
the Python 3.2 version of the email package. For more information see the
:mod:`~email.policy` documentation.
.. versionchanged:: 3.3 The *policy* keyword argument was added.
.. method:: as_string(unixfrom=False, maxheaderlen=0, policy=None)
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``. For backward compatibility reasons,
*maxheaderlen* defaults to ``0``, so if you want a different value you
must override it explicitly (the value specified for *max_line_length* in
the policy will be ignored by this method). The *policy* argument may be
used to override the default policy obtained from the message instance.
This can be used to control some of the formatting produced by the
method, since the specified *policy* will be passed to the ``Generator``.
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 does
not do the mangling of lines that begin with ``From`` that is
required by the unix mbox format. For more flexibility, instantiate a
:class:`~email.generator.Generator` instance and use its
:meth:`~email.generator.Generator.flatten` method directly. For example::
from io import StringIO
from email.generator import Generator
fp = StringIO()
g = Generator(fp, mangle_from_=True, maxheaderlen=60)
g.flatten(msg)
text = fp.getvalue()
If the message object contains binary data that is not encoded according
to RFC standards, the non-compliant data will be replaced by unicode
"unknown character" code points. (See also :meth:`.as_bytes` and
:class:`~email.generator.BytesGenerator`.)
.. versionchanged:: 3.4 the *policy* keyword argument was added.
.. method:: __str__()
Equivalent to :meth:`.as_string()`. Allows ``str(msg)`` to produce a
string containing the formatted message.
.. method:: as_bytes(unixfrom=False, policy=None)
Return the entire message flattened as a bytes object. When optional
*unixfrom* is true, the envelope header is included in the returned
string. *unixfrom* defaults to ``False``. The *policy* argument may be
used to override the default policy obtained from the message instance.
This can be used to control some of the formatting produced by the
method, since the specified *policy* will be passed to the
``BytesGenerator``.
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 does
not do the mangling of lines that begin with ``From`` that is
required by the unix mbox format. For more flexibility, instantiate a
:class:`~email.generator.BytesGenerator` instance and use its
:meth:`~email.generator.BytesGenerator.flatten` method directly.
For example::
from io import BytesIO
from email.generator import BytesGenerator
fp = BytesIO()
g = BytesGenerator(fp, mangle_from_=True, maxheaderlen=60)
g.flatten(msg)
text = fp.getvalue()
.. versionadded:: 3.4
.. method:: __bytes__()
Equivalent to :meth:`.as_bytes()`. Allows ``bytes(msg)`` to produce a
bytes object containing the formatted message.
.. versionadded:: 3.4
.. 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 (which might be a CTE encoded binary payload). (Note that
:meth:`is_multipart` returning ``True`` does not necessarily mean that
"msg.get_content_maintype() == 'multipart'" will return the ``True``.
For example, ``is_multipart`` will return ``True`` when the
:class:`Message` is of type ``message/rfc822``.)
.. 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.
This is a legacy method. On the
:class:`~email.emailmessage.EmailMessage` class its functionality is
replaced by :meth:`~email.message.EmailMessage.set_content` and the
related ``make`` and ``add`` methods.
.. method:: get_payload(i=None, decode=False)
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, the payload is
returned as-is (undecoded). In all cases the returned value is binary
data. If the message is a multipart and the *decode* flag is ``True``,
then ``None`` is returned. If the payload is base64 and it was not
perfectly formed (missing padding, characters outside the base64
alphabet), then an appropriate defect will be added to the message's
defect property (:class:`~email.errors.InvalidBase64PaddingDefect` or
:class:`~email.errors.InvalidBase64CharactersDefect`, respectively).
When *decode* is ``False`` (the default) the body is returned as a string
without decoding the :mailheader:`Content-Transfer-Encoding`. However,
for a :mailheader:`Content-Transfer-Encoding` of 8bit, an attempt is made
to decode the original bytes using the ``charset`` specified by the
:mailheader:`Content-Type` header, using the ``replace`` error handler.
If no ``charset`` is specified, or if the ``charset`` given is not
recognized by the email package, the body is decoded using the default
ASCII charset.
This is a legacy method. On the
:class:`~email.emailmessage.EmailMessage` class its functionality is
replaced by :meth:`~email.message.EmailMessage.get_content` and
:meth:`~email.message.EmailMessage.iter_parts`.
.. method:: set_payload(payload, charset=None)
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.
This is a legacy method. On the
:class:`~email.emailmessage.EmailMessage` class its functionality is
replaced by :meth:`~email.message.EmailMessage.set_content`.
.. 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.
This is a legacy method. On the
:class:`~email.emailmessage.EmailMessage` class its functionality is
replaced by the *charset* parameter of the
:meth:`email.emailmessage.EmailMessage.set_content` method.
.. method:: get_charset()
Return the :class:`~email.charset.Charset` instance associated with the
message's payload.
This is a legacy method. On the
:class:`~email.emailmessage.EmailMessage` class it always returns
``None``.
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.
In a model generated from bytes, any header values that (in contravention of
the RFCs) contain non-ASCII bytes will, when retrieved through this
interface, be represented as :class:`~email.header.Header` objects with
a charset of `unknown-8bit`.
.. 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:: 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=None)
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=None)
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 can 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. If
a three tuple is not passed and the value contains non-ASCII characters,
it is automatically encoded in :rfc:`2231` format using a ``CHARSET``
of ``utf-8`` and a ``LANGUAGE`` of ``None``.
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.
.. 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`.
.. 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`.
.. 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`.
.. 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`.
.. 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.
.. method:: get_params(failobj=None, header='content-type', unquote=True)
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`.
This is a legacy method. On the
:class:`~email.emailmessage.EmailMessage` class its functionality is
replaced by the *params* property of the individual header objects
returned by the header access methods.
.. method:: get_param(param, failobj=None, header='content-type', unquote=True)
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``.
This is a legacy method. On the
:class:`~email.emailmessage.EmailMessage` class its functionality is
replaced by the *params* property of the individual header objects
returned by the header access methods.
.. method:: set_param(param, value, header='Content-Type', requote=True, \
charset=None, language='', replace=False)
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.
If *replace* is ``False`` (the default) the header is moved to the
end of the list of headers. If *replace* is ``True``, the header
will be updated in place.
.. versionchanged:: 3.4 ``replace`` keyword was added.
.. method:: del_param(param, header='content-type', requote=True)
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`.
.. method:: set_type(type, header='Content-Type', requote=True)
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.
This is a legacy method. On the
:class:`~email.emailmessage.EmailMessage` class its functionality is
replaced by the ``make_`` and ``add_`` methods.
.. method:: get_filename(failobj=None)
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=None)
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=None)
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.
.. method:: get_charsets(failobj=None)
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:: get_content_disposition()
Return the lowercased value (without parameters) of the message's
:mailheader:`Content-Disposition` header if it has one, or ``None``. The
possible values for this method are *inline*, *attachment* or ``None``
if the message follows :rfc:`2183`.
.. versionadded:: 3.5
.. 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:
.. testsetup::
import email
from email import message_from_binary_file
from os.path import join, dirname
lib_dir = dirname(dirname(email.__file__))
file_path = join(lib_dir, 'test/test_email/data/msg_16.txt')
with open(file_path, 'rb') as f:
msg = message_from_binary_file(f)
from email.iterators import _structure
.. doctest::
>>> for part in msg.walk():
... print(part.get_content_type())
multipart/report
text/plain
message/delivery-status
text/plain
text/plain
message/rfc822
text/plain
``walk`` iterates over the subparts of any part where
:meth:`is_multipart` returns ``True``, even though
``msg.get_content_maintype() == 'multipart'`` may return ``False``. We
can see this in our example by making use of the ``_structure`` debug
helper function:
.. doctest::
>>> for part in msg.walk():
... print(part.get_content_maintype() == 'multipart',
... part.is_multipart())
True True
False False
False True
False False
False False
False True
False False
>>> _structure(msg)
multipart/report
text/plain
message/delivery-status
text/plain
text/plain
message/rfc822
text/plain
Here the ``message`` parts are not ``multiparts``, but they do contain
subparts. ``is_multipart()`` returns ``True`` and ``walk`` descends
into the subparts.
: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.
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.

198
web/python-docs/_sources/library/email.contentmanager.rst.txt Normal file
View File

@@ -0,0 +1,198 @@
:mod:`email.contentmanager`: Managing MIME Content
--------------------------------------------------
.. module:: email.contentmanager
:synopsis: Storing and Retrieving Content from MIME Parts
.. moduleauthor:: R. David Murray <rdmurray@bitdance.com>
.. sectionauthor:: R. David Murray <rdmurray@bitdance.com>
**Source code:** :source:`Lib/email/contentmanager.py`
------------
.. versionadded:: 3.6 [1]_
.. class:: ContentManager()
Base class for content managers. Provides the standard registry mechanisms
to register converters between MIME content and other representations, as
well as the ``get_content`` and ``set_content`` dispatch methods.
.. method:: get_content(msg, *args, **kw)
Look up a handler function based on the ``mimetype`` of *msg* (see next
paragraph), call it, passing through all arguments, and return the result
of the call. The expectation is that the handler will extract the
payload from *msg* and return an object that encodes information about
the extracted data.
To find the handler, look for the following keys in the registry,
stopping with the first one found:
* the string representing the full MIME type (``maintype/subtype``)
* the string representing the ``maintype``
* the empty string
If none of these keys produce a handler, raise a :exc:`KeyError` for the
full MIME type.
.. method:: set_content(msg, obj, *args, **kw)
If the ``maintype`` is ``multipart``, raise a :exc:`TypeError`; otherwise
look up a handler function based on the type of *obj* (see next
paragraph), call :meth:`~email.message.EmailMessage.clear_content` on the
*msg*, and call the handler function, passing through all arguments. The
expectation is that the handler will transform and store *obj* into
*msg*, possibly making other changes to *msg* as well, such as adding
various MIME headers to encode information needed to interpret the stored
data.
To find the handler, obtain the type of *obj* (``typ = type(obj)``), and
look for the following keys in the registry, stopping with the first one
found:
* the type itself (``typ``)
* the type's fully qualified name (``typ.__module__ + '.' +
typ.__qualname__``).
* the type's qualname (``typ.__qualname__``)
* the type's name (``typ.__name__``).
If none of the above match, repeat all of the checks above for each of
the types in the :term:`MRO` (``typ.__mro__``). Finally, if no other key
yields a handler, check for a handler for the key ``None``. If there is
no handler for ``None``, raise a :exc:`KeyError` for the fully
qualified name of the type.
Also add a :mailheader:`MIME-Version` header if one is not present (see
also :class:`.MIMEPart`).
.. method:: add_get_handler(key, handler)
Record the function *handler* as the handler for *key*. For the possible
values of *key*, see :meth:`get_content`.
.. method:: add_set_handler(typekey, handler)
Record *handler* as the function to call when an object of a type
matching *typekey* is passed to :meth:`set_content`. For the possible
values of *typekey*, see :meth:`set_content`.
Content Manager Instances
~~~~~~~~~~~~~~~~~~~~~~~~~
Currently the email package provides only one concrete content manager,
:data:`raw_data_manager`, although more may be added in the future.
:data:`raw_data_manager` is the
:attr:`~email.policy.EmailPolicy.content_manager` provided by
:attr:`~email.policy.EmailPolicy` and its derivatives.
.. data:: raw_data_manager
This content manager provides only a minimum interface beyond that provided
by :class:`~email.message.Message` itself: it deals only with text, raw
byte strings, and :class:`~email.message.Message` objects. Nevertheless, it
provides significant advantages compared to the base API: ``get_content`` on
a text part will return a unicode string without the application needing to
manually decode it, ``set_content`` provides a rich set of options for
controlling the headers added to a part and controlling the content transfer
encoding, and it enables the use of the various ``add_`` methods, thereby
simplifying the creation of multipart messages.
.. method:: get_content(msg, errors='replace')
Return the payload of the part as either a string (for ``text`` parts), an
:class:`~email.message.EmailMessage` object (for ``message/rfc822``
parts), or a ``bytes`` object (for all other non-multipart types). Raise
a :exc:`KeyError` if called on a ``multipart``. If the part is a
``text`` part and *errors* is specified, use it as the error handler when
decoding the payload to unicode. The default error handler is
``replace``.
.. method:: set_content(msg, <'str'>, subtype="plain", charset='utf-8', \
cte=None, \
disposition=None, filename=None, cid=None, \
params=None, headers=None)
set_content(msg, <'bytes'>, maintype, subtype, cte="base64", \
disposition=None, filename=None, cid=None, \
params=None, headers=None)
set_content(msg, <'EmailMessage'>, cte=None, \
disposition=None, filename=None, cid=None, \
params=None, headers=None)
Add headers and payload to *msg*:
Add a :mailheader:`Content-Type` header with a ``maintype/subtype``
value.
* For ``str``, set the MIME ``maintype`` to ``text``, and set the
subtype to *subtype* if it is specified, or ``plain`` if it is not.
* For ``bytes``, use the specified *maintype* and *subtype*, or
raise a :exc:`TypeError` if they are not specified.
* For :class:`~email.message.EmailMessage` objects, set the maintype
to ``message``, and set the subtype to *subtype* if it is
specified or ``rfc822`` if it is not. If *subtype* is
``partial``, raise an error (``bytes`` objects must be used to
construct ``message/partial`` parts).
If *charset* is provided (which is valid only for ``str``), encode the
string to bytes using the specified character set. The default is
``utf-8``. If the specified *charset* is a known alias for a standard
MIME charset name, use the standard charset instead.
If *cte* is set, encode the payload using the specified content transfer
encoding, and set the :mailheader:`Content-Transfer-Encoding` header to
that value. Possible values for *cte* are ``quoted-printable``,
``base64``, ``7bit``, ``8bit``, and ``binary``. If the input cannot be
encoded in the specified encoding (for example, specifying a *cte* of
``7bit`` for an input that contains non-ASCII values), raise a
:exc:`ValueError`.
* For ``str`` objects, if *cte* is not set use heuristics to
determine the most compact encoding.
* For :class:`~email.message.EmailMessage`, per :rfc:`2046`, raise
an error if a *cte* of ``quoted-printable`` or ``base64`` is
requested for *subtype* ``rfc822``, and for any *cte* other than
``7bit`` for *subtype* ``external-body``. For
``message/rfc822``, use ``8bit`` if *cte* is not specified. For
all other values of *subtype*, use ``7bit``.
.. note:: A *cte* of ``binary`` does not actually work correctly yet.
The ``EmailMessage`` object as modified by ``set_content`` is
correct, but :class:`~email.generator.BytesGenerator` does not
serialize it correctly.
If *disposition* is set, use it as the value of the
:mailheader:`Content-Disposition` header. If not specified, and
*filename* is specified, add the header with the value ``attachment``.
If *disposition* is not specified and *filename* is also not specified,
do not add the header. The only valid values for *disposition* are
``attachment`` and ``inline``.
If *filename* is specified, use it as the value of the ``filename``
parameter of the :mailheader:`Content-Disposition` header.
If *cid* is specified, add a :mailheader:`Content-ID` header with
*cid* as its value.
If *params* is specified, iterate its ``items`` method and use the
resulting ``(key, value)`` pairs to set additional parameters on the
:mailheader:`Content-Type` header.
If *headers* is specified and is a list of strings of the form
``headername: headervalue`` or a list of ``header`` objects
(distinguished from strings by having a ``name`` attribute), add the
headers to *msg*.
.. rubric:: Footnotes
.. [1] Originally added in 3.4 as a :term:`provisional module <provisional
package>`

75
web/python-docs/_sources/library/email.encoders.rst.txt Normal file
View File

@@ -0,0 +1,75 @@
:mod:`email.encoders`: Encoders
-------------------------------
.. module:: email.encoders
:synopsis: Encoders for email message payloads.
**Source code:** :source:`Lib/email/encoders.py`
--------------
This module is part of the legacy (``Compat32``) email API. In the
new API the functionality is provided by the *cte* parameter of
the :meth:`~email.message.EmailMessage.set_content` method.
This module is deprecated in Python 3. The functions provided here
should not be called explicitly since the :class:`~email.mime.text.MIMEText`
class sets the content type and CTE header using the *_subtype* and *_charset*
values passed during the instaniation of that class.
The remaining text in this section is the original documentation of the module.
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 encoders 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.

120
web/python-docs/_sources/library/email.errors.rst.txt Normal file
View File

@@ -0,0 +1,120 @@
:mod:`email.errors`: Exception and Defect classes
-------------------------------------------------
.. module:: email.errors
:synopsis: The exception classes used by the email package.
**Source code:** :source:`Lib/email/errors.py`
--------------
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`. This class is also used internally by the parser used
by :mod:`~email.headerregistry`.
.. exception:: HeaderParseError()
Raised under some error conditions when parsing the :rfc:`5322` headers of a
message, this class is derived from :exc:`MessageParseError`. The
:meth:`~email.message.EmailMessage.set_boundary` method will raise this
error if the content type is unknown when the method is called.
:class:`~email.header.Header` may raise this error for certain base64
decoding errors, and when an attempt is made to create a header that appears
to contain an embedded header (that is, there is what is supposed to be a
continuation line that has no leading whitespace and looks like a header).
.. exception:: BoundaryError()
Deprecated and no longer 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`).
.. exception:: HeaderWriteError()
Raised when an error occurs when the :mod:`~email.generator` outputs
headers.
Here is 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`.
* :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:`CloseBoundaryNotFoundDefect` -- A start boundary was found, but
no corresponding close boundary was ever found.
.. versionadded:: 3.3
* :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:`MissingHeaderBodySeparatorDefect` - A line was found while parsing
headers that had no leading white space but contained no ':'. Parsing
continues assuming that the line represents the first line of the body.
.. versionadded:: 3.3
* :class:`MalformedHeaderDefect` -- A header was found that was missing a colon,
or was otherwise malformed.
.. deprecated:: 3.3
This defect has not been used for several Python versions.
* :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`.
* :class:`InvalidBase64PaddingDefect` -- When decoding a block of base64
encoded bytes, the padding was not correct. Enough padding is added to
perform the decode, but the resulting decoded bytes may be invalid.
* :class:`InvalidBase64CharactersDefect` -- When decoding a block of base64
encoded bytes, characters outside the base64 alphabet were encountered.
The characters are ignored, but the resulting decoded bytes may be invalid.
* :class:`InvalidBase64LengthDefect` -- When decoding a block of base64 encoded
bytes, the number of non-padding base64 characters was invalid (1 more than
a multiple of 4). The encoded block was kept as-is.

67
web/python-docs/_sources/library/email.examples.rst.txt Normal file
View File

@@ -0,0 +1,67 @@
.. _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 (both the
text content and the addresses may contain unicode characters):
.. literalinclude:: ../includes/email-simple.py
Parsing :rfc:`822` headers can easily be done by the using the classes
from the :mod:`~email.parser` module:
.. 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. To make things a bit more interesting, we include a related
image in the html part, and we save a copy of what we are going to send to
disk, as well as sending it.
.. literalinclude:: ../includes/email-alternative.py
If we were sent the message from the last example, here is one way we could
process it:
.. literalinclude:: ../includes/email-read-alternative.py
Up to the prompt, the output from the above is:
.. code-block:: none
To: Penelope Pussycat <penelope@example.com>, Fabrette Pussycat <fabrette@example.com>
From: Pepé Le Pew <pepe@example.com>
Subject: Ayons asperges pour le déjeuner
Salut!
Cela ressemble à un excellent recipie[1] déjeuner.
.. rubric:: Footnotes
.. [1] Thanks to Matthew Dixon Cowles for the original inspiration and examples.

283
web/python-docs/_sources/library/email.generator.rst.txt Normal file
View File

@@ -0,0 +1,283 @@
:mod:`email.generator`: Generating MIME documents
-------------------------------------------------
.. module:: email.generator
:synopsis: Generate flat text email messages from a message structure.
**Source code:** :source:`Lib/email/generator.py`
--------------
One of the most common tasks is to generate the flat (serialized) version of
the email message represented by a message object structure. You will need to
do this if you want to send your message via :meth:`smtplib.SMTP.sendmail` or
the :mod:`nntplib` module, or print the message on the console. Taking a
message object structure and producing a serialized representation is the job
of the generator classes.
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 bytes-oriented parsing and generation operations are inverses,
assuming the same non-transforming :mod:`~email.policy` is used for both. That
is, parsing the serialized byte stream via the
:class:`~email.parser.BytesParser` class and then regenerating the serialized
byte stream using :class:`BytesGenerator` should produce output identical to
the input [#]_. (On the other hand, using the generator on an
:class:`~email.message.EmailMessage` constructed by program may result in
changes to the :class:`~email.message.EmailMessage` object as defaults are
filled in.)
The :class:`Generator` class can be used to flatten a message into a text (as
opposed to binary) serialized representation, but since Unicode cannot
represent binary data directly, the message is of necessity transformed into
something that contains only ASCII characters, using the standard email RFC
Content Transfer Encoding techniques for encoding email messages for transport
over channels that are not "8 bit clean".
To accommodate reproducible processing of SMIME-signed messages
:class:`Generator` disables header folding for message parts of type
``multipart/signed`` and all subparts.
.. class:: BytesGenerator(outfp, mangle_from_=None, maxheaderlen=None, *, \
policy=None)
Return a :class:`BytesGenerator` object that will write any message provided
to the :meth:`flatten` method, or any surrogateescape encoded text provided
to the :meth:`write` method, to the :term:`file-like object` *outfp*.
*outfp* must support a ``write`` method that accepts binary data.
If optional *mangle_from_* is ``True``, put a ``>`` character in front of
any line in the body that starts with the exact string ``"From "``, that is
``From`` followed by a space at the beginning of a line. *mangle_from_*
defaults to the value of the :attr:`~email.policy.Policy.mangle_from_`
setting of the *policy* (which is ``True`` for the
:data:`~email.policy.compat32` policy and ``False`` for all others).
*mangle_from_* is intended for use when messages are stored in unix mbox
format (see :mod:`mailbox` and `WHY THE CONTENT-LENGTH FORMAT IS BAD
<https://www.jwz.org/doc/content-length.html>`_).
If *maxheaderlen* is not ``None``, refold any header lines that are longer
than *maxheaderlen*, or if ``0``, do not rewrap any headers. If
*manheaderlen* is ``None`` (the default), wrap headers and other message
lines according to the *policy* settings.
If *policy* is specified, use that policy to control message generation. If
*policy* is ``None`` (the default), use the policy associated with the
:class:`~email.message.Message` or :class:`~email.message.EmailMessage`
object passed to ``flatten`` to control the message generation. See
:mod:`email.policy` for details on what *policy* controls.
.. versionadded:: 3.2
.. versionchanged:: 3.3 Added the *policy* keyword.
.. versionchanged:: 3.6 The default behavior of the *mangle_from_*
and *maxheaderlen* parameters is to follow the policy.
.. method:: flatten(msg, unixfrom=False, linesep=None)
Print the textual representation of the message object structure rooted
at *msg* to the output file specified when the :class:`BytesGenerator`
instance was created.
If the :mod:`~email.policy` option :attr:`~email.policy.Policy.cte_type`
is ``8bit`` (the default), copy any headers in the original parsed
message that have not been modified to the output with any bytes with the
high bit set reproduced as in the original, and preserve the non-ASCII
:mailheader:`Content-Transfer-Encoding` of any body parts that have them.
If ``cte_type`` is ``7bit``, convert the bytes with the high bit set as
needed using an ASCII-compatible :mailheader:`Content-Transfer-Encoding`.
That is, transform parts with non-ASCII
:mailheader:`Content-Transfer-Encoding`
(:mailheader:`Content-Transfer-Encoding: 8bit`) to an ASCII compatible
:mailheader:`Content-Transfer-Encoding`, and encode RFC-invalid non-ASCII
bytes in headers using the MIME ``unknown-8bit`` character set, thus
rendering them RFC-compliant.
.. XXX: There should be an option that just does the RFC
compliance transformation on headers but leaves CTE 8bit parts alone.
If *unixfrom* is ``True``, print the envelope header delimiter used by
the Unix mailbox format (see :mod:`mailbox`) before the first of the
:rfc:`5322` headers of the root message object. If the root object has
no envelope header, craft a standard one. The default is ``False``.
Note that for subparts, no envelope header is ever printed.
If *linesep* is not ``None``, use it as the separator character between
all the lines of the flattened message. If *linesep* is ``None`` (the
default), use the value specified in the *policy*.
.. XXX: flatten should take a *policy* keyword.
.. method:: clone(fp)
Return an independent clone of this :class:`BytesGenerator` instance with
the exact same option settings, and *fp* as the new *outfp*.
.. method:: write(s)
Encode *s* using the ``ASCII`` codec and the ``surrogateescape`` error
handler, and pass it to the *write* method of the *outfp* passed to the
:class:`BytesGenerator`'s constructor.
As a convenience, :class:`~email.message.EmailMessage` provides the methods
:meth:`~email.message.EmailMessage.as_bytes` and ``bytes(aMessage)`` (a.k.a.
:meth:`~email.message.EmailMessage.__bytes__`), which simplify the generation of
a serialized binary representation of a message object. For more detail, see
:mod:`email.message`.
Because strings cannot represent binary data, the :class:`Generator` class must
convert any binary data in any message it flattens to an ASCII compatible
format, by converting them to an ASCII compatible
:mailheader:`Content-Transfer_Encoding`. Using the terminology of the email
RFCs, you can think of this as :class:`Generator` serializing to an I/O stream
that is not "8 bit clean". In other words, most applications will want
to be using :class:`BytesGenerator`, and not :class:`Generator`.
.. class:: Generator(outfp, mangle_from_=None, maxheaderlen=None, *, \
policy=None)
Return a :class:`Generator` object that will write any message provided
to the :meth:`flatten` method, or any text provided to the :meth:`write`
method, to the :term:`file-like object` *outfp*. *outfp* must support a
``write`` method that accepts string data.
If optional *mangle_from_* is ``True``, put a ``>`` character in front of
any line in the body that starts with the exact string ``"From "``, that is
``From`` followed by a space at the beginning of a line. *mangle_from_*
defaults to the value of the :attr:`~email.policy.Policy.mangle_from_`
setting of the *policy* (which is ``True`` for the
:data:`~email.policy.compat32` policy and ``False`` for all others).
*mangle_from_* is intended for use when messages are stored in unix mbox
format (see :mod:`mailbox` and `WHY THE CONTENT-LENGTH FORMAT IS BAD
<https://www.jwz.org/doc/content-length.html>`_).
If *maxheaderlen* is not ``None``, refold any header lines that are longer
than *maxheaderlen*, or if ``0``, do not rewrap any headers. If
*manheaderlen* is ``None`` (the default), wrap headers and other message
lines according to the *policy* settings.
If *policy* is specified, use that policy to control message generation. If
*policy* is ``None`` (the default), use the policy associated with the
:class:`~email.message.Message` or :class:`~email.message.EmailMessage`
object passed to ``flatten`` to control the message generation. See
:mod:`email.policy` for details on what *policy* controls.
.. versionchanged:: 3.3 Added the *policy* keyword.
.. versionchanged:: 3.6 The default behavior of the *mangle_from_*
and *maxheaderlen* parameters is to follow the policy.
.. method:: flatten(msg, unixfrom=False, linesep=None)
Print the textual representation of the message object structure rooted
at *msg* to the output file specified when the :class:`Generator`
instance was created.
If the :mod:`~email.policy` option :attr:`~email.policy.Policy.cte_type`
is ``8bit``, generate the message as if the option were set to ``7bit``.
(This is required because strings cannot represent non-ASCII bytes.)
Convert any bytes with the high bit set as needed using an
ASCII-compatible :mailheader:`Content-Transfer-Encoding`. That is,
transform parts with non-ASCII :mailheader:`Content-Transfer-Encoding`
(:mailheader:`Content-Transfer-Encoding: 8bit`) to an ASCII compatible
:mailheader:`Content-Transfer-Encoding`, and encode RFC-invalid non-ASCII
bytes in headers using the MIME ``unknown-8bit`` character set, thus
rendering them RFC-compliant.
If *unixfrom* is ``True``, print the envelope header delimiter used by
the Unix mailbox format (see :mod:`mailbox`) before the first of the
:rfc:`5322` headers of the root message object. If the root object has
no envelope header, craft a standard one. The default is ``False``.
Note that for subparts, no envelope header is ever printed.
If *linesep* is not ``None``, use it as the separator character between
all the lines of the flattened message. If *linesep* is ``None`` (the
default), use the value specified in the *policy*.
.. XXX: flatten should take a *policy* keyword.
.. versionchanged:: 3.2
Added support for re-encoding ``8bit`` message bodies, and the
*linesep* argument.
.. method:: clone(fp)
Return an independent clone of this :class:`Generator` instance with the
exact same options, and *fp* as the new *outfp*.
.. method:: write(s)
Write *s* to the *write* method of the *outfp* passed to the
:class:`Generator`'s constructor. This provides just enough file-like
API for :class:`Generator` instances to be used in the :func:`print`
function.
As a convenience, :class:`~email.message.EmailMessage` provides the methods
:meth:`~email.message.EmailMessage.as_string` and ``str(aMessage)`` (a.k.a.
:meth:`~email.message.EmailMessage.__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,
:class:`DecodedGenerator`, which is like the :class:`Generator` base class,
except that non-\ :mimetype:`text` parts are not serialized, but are instead
represented in the output stream by a string derived from a template filled
in with information about the part.
.. class:: DecodedGenerator(outfp, mangle_from_=None, maxheaderlen=None, \
fmt=None, *, policy=None)
Act like :class:`Generator`, except that for any subpart of the message
passed to :meth:`Generator.flatten`, if the subpart is of main type
:mimetype:`text`, print the decoded payload of the subpart, and if the main
type is not :mimetype:`text`, instead of printing it fill in the string
*fmt* using information from the part and print the resulting
filled-in string.
To fill in *fmt*, execute ``fmt % part_info``, where ``part_info``
is a dictionary composed of the following keys and values:
* ``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
If *fmt* is ``None``, use the following default *fmt*:
"[Non-text (%(type)s) part of message omitted, filename %(filename)s]"
Optional *_mangle_from_* and *maxheaderlen* are as with the
:class:`Generator` base class.
.. rubric:: Footnotes
.. [#] This statement assumes that you use the appropriate setting for
``unixfrom``, and that there are no :mod:`policy` settings calling for
automatic adjustments (for example,
:attr:`~email.policy.Policy.refold_source` must be ``none``, which is
*not* the default). It is also not 100% true, since if the message
does not conform to the RFC standards occasionally information about the
exact original text is lost during parsing error recovery. It is a goal
to fix these latter edge cases when possible.

205
web/python-docs/_sources/library/email.header.rst.txt Normal file
View File

@@ -0,0 +1,205 @@
:mod:`email.header`: Internationalized headers
----------------------------------------------
.. module:: email.header
:synopsis: Representing non-ASCII headers
**Source code:** :source:`Lib/email/header.py`
--------------
This module is part of the legacy (``Compat32``) email API. In the current API
encoding and decoding of headers is handled transparently by the
dictionary-like API of the :class:`~email.message.EmailMessage` class. In
addition to uses in legacy code, this module can be useful in applications that
need to completely control the character sets used when encoding headers.
The remaining text in this section is the original documentation of the module.
: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
>>> msg.as_string()
'Subject: =?iso-8859-1?q?p=F6stal?=\n\n'
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.
Here is the :class:`Header` class description:
.. class:: Header(s=None, charset=None, maxlinelen=None, header_name=None, continuation_ws=' ', errors='strict')
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 an instance of :class:`bytes` or
:class:`str`, 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=None, errors='strict')
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 an instance of :class:`bytes` or :class:`str`. If it is an
instance of :class:`bytes`, 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 an instance of :class:`str`, then *charset* is a hint specifying
the character set of the characters in the string.
In either case, when producing an :rfc:`2822`\ -compliant header using
:rfc:`2047` rules, the string will be encoded using the output codec of
the charset. If the string cannot be encoded using the output codec, a
UnicodeError will be raised.
Optional *errors* is passed as the errors argument to the decode call
if *s* is a byte string.
.. method:: encode(splitchars=';, \\t', maxlinelen=None, linesep='\\n')
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 which should be
given extra weight by the splitting algorithm during normal header
wrapping. This is in very rough support of :RFC:`2822`\'s 'higher level
syntactic breaks': split points preceded by a splitchar are preferred
during line splitting, with the characters preferred in the order in
which they appear in the string. Space and tab may be included in the
string to indicate whether preference should be given to one over the
other as a split point when other split chars do not appear in the line
being split. Splitchars does not affect :RFC:`2047` encoded lines.
*maxlinelen*, if given, overrides the instance's value for the maximum
line length.
*linesep* specifies the characters used to separate the lines of the
folded header. It defaults to the most useful value for Python
application code (``\n``), but ``\r\n`` can be specified in order
to produce headers with RFC-compliant line separators.
.. versionchanged:: 3.2
Added the *linesep* argument.
The :class:`Header` class also provides a number of methods to support
standard operators and built-in functions.
.. method:: __str__()
Returns an approximation of the :class:`Header` as a string, using an
unlimited line length. All pieces are converted to unicode using the
specified encoding and joined together appropriately. Any pieces with a
charset of ``'unknown-8bit'`` are decoded as ASCII using the ``'replace'``
error handler.
.. versionchanged:: 3.2
Added handling for the ``'unknown-8bit'`` charset.
.. 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?=')
[(b'p\xf6stal', 'iso-8859-1')]
.. function:: make_header(decoded_seq, maxlinelen=None, header_name=None, 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.

462
web/python-docs/_sources/library/email.headerregistry.rst.txt Normal file
View File

@@ -0,0 +1,462 @@
:mod:`email.headerregistry`: Custom Header Objects
--------------------------------------------------
.. module:: email.headerregistry
:synopsis: Automatic Parsing of headers based on the field name
.. moduleauthor:: R. David Murray <rdmurray@bitdance.com>
.. sectionauthor:: R. David Murray <rdmurray@bitdance.com>
**Source code:** :source:`Lib/email/headerregistry.py`
--------------
.. versionadded:: 3.6 [1]_
Headers are represented by customized subclasses of :class:`str`. The
particular class used to represent a given header is determined by the
:attr:`~email.policy.EmailPolicy.header_factory` of the :mod:`~email.policy` in
effect when the headers are created. This section documents the particular
``header_factory`` implemented by the email package for handling :RFC:`5322`
compliant email messages, which not only provides customized header objects for
various header types, but also provides an extension mechanism for applications
to add their own custom header types.
When using any of the policy objects derived from
:data:`~email.policy.EmailPolicy`, all headers are produced by
:class:`.HeaderRegistry` and have :class:`.BaseHeader` as their last base
class. Each header class has an additional base class that is determined by
the type of the header. For example, many headers have the class
:class:`.UnstructuredHeader` as their other base class. The specialized second
class for a header is determined by the name of the header, using a lookup
table stored in the :class:`.HeaderRegistry`. All of this is managed
transparently for the typical application program, but interfaces are provided
for modifying the default behavior for use by more complex applications.
The sections below first document the header base classes and their attributes,
followed by the API for modifying the behavior of :class:`.HeaderRegistry`, and
finally the support classes used to represent the data parsed from structured
headers.
.. class:: BaseHeader(name, value)
*name* and *value* are passed to ``BaseHeader`` from the
:attr:`~email.policy.EmailPolicy.header_factory` call. The string value of
any header object is the *value* fully decoded to unicode.
This base class defines the following read-only properties:
.. attribute:: name
The name of the header (the portion of the field before the ':'). This
is exactly the value passed in the
:attr:`~email.policy.EmailPolicy.header_factory` call for *name*; that
is, case is preserved.
.. attribute:: defects
A tuple of :exc:`~email.errors.HeaderDefect` instances reporting any
RFC compliance problems found during parsing. The email package tries to
be complete about detecting compliance issues. See the :mod:`~email.errors`
module for a discussion of the types of defects that may be reported.
.. attribute:: max_count
The maximum number of headers of this type that can have the same
``name``. A value of ``None`` means unlimited. The ``BaseHeader`` value
for this attribute is ``None``; it is expected that specialized header
classes will override this value as needed.
``BaseHeader`` also provides the following method, which is called by the
email library code and should not in general be called by application
programs:
.. method:: fold(*, policy)
Return a string containing :attr:`~email.policy.Policy.linesep`
characters as required to correctly fold the header according to
*policy*. A :attr:`~email.policy.Policy.cte_type` of ``8bit`` will be
treated as if it were ``7bit``, since headers may not contain arbitrary
binary data. If :attr:`~email.policy.EmailPolicy.utf8` is ``False``,
non-ASCII data will be :rfc:`2047` encoded.
``BaseHeader`` by itself cannot be used to create a header object. It
defines a protocol that each specialized header cooperates with in order to
produce the header object. Specifically, ``BaseHeader`` requires that
the specialized class provide a :func:`classmethod` named ``parse``. This
method is called as follows::
parse(string, kwds)
``kwds`` is a dictionary containing one pre-initialized key, ``defects``.
``defects`` is an empty list. The parse method should append any detected
defects to this list. On return, the ``kwds`` dictionary *must* contain
values for at least the keys ``decoded`` and ``defects``. ``decoded``
should be the string value for the header (that is, the header value fully
decoded to unicode). The parse method should assume that *string* may
contain content-transfer-encoded parts, but should correctly handle all valid
unicode characters as well so that it can parse un-encoded header values.
``BaseHeader``'s ``__new__`` then creates the header instance, and calls its
``init`` method. The specialized class only needs to provide an ``init``
method if it wishes to set additional attributes beyond those provided by
``BaseHeader`` itself. Such an ``init`` method should look like this::
def init(self, /, *args, **kw):
self._myattr = kw.pop('myattr')
super().init(*args, **kw)
That is, anything extra that the specialized class puts in to the ``kwds``
dictionary should be removed and handled, and the remaining contents of
``kw`` (and ``args``) passed to the ``BaseHeader`` ``init`` method.
.. class:: UnstructuredHeader
An "unstructured" header is the default type of header in :rfc:`5322`.
Any header that does not have a specified syntax is treated as
unstructured. The classic example of an unstructured header is the
:mailheader:`Subject` header.
In :rfc:`5322`, an unstructured header is a run of arbitrary text in the
ASCII character set. :rfc:`2047`, however, has an :rfc:`5322` compatible
mechanism for encoding non-ASCII text as ASCII characters within a header
value. When a *value* containing encoded words is passed to the
constructor, the ``UnstructuredHeader`` parser converts such encoded words
into unicode, following the :rfc:`2047` rules for unstructured text. The
parser uses heuristics to attempt to decode certain non-compliant encoded
words. Defects are registered in such cases, as well as defects for issues
such as invalid characters within the encoded words or the non-encoded text.
This header type provides no additional attributes.
.. class:: DateHeader
:rfc:`5322` specifies a very specific format for dates within email headers.
The ``DateHeader`` parser recognizes that date format, as well as
recognizing a number of variant forms that are sometimes found "in the
wild".
This header type provides the following additional attributes:
.. attribute:: datetime
If the header value can be recognized as a valid date of one form or
another, this attribute will contain a :class:`~datetime.datetime`
instance representing that date. If the timezone of the input date is
specified as ``-0000`` (indicating it is in UTC but contains no
information about the source timezone), then :attr:`.datetime` will be a
naive :class:`~datetime.datetime`. If a specific timezone offset is
found (including `+0000`), then :attr:`.datetime` will contain an aware
``datetime`` that uses :class:`datetime.timezone` to record the timezone
offset.
The ``decoded`` value of the header is determined by formatting the
``datetime`` according to the :rfc:`5322` rules; that is, it is set to::
email.utils.format_datetime(self.datetime)
When creating a ``DateHeader``, *value* may be
:class:`~datetime.datetime` instance. This means, for example, that
the following code is valid and does what one would expect::
msg['Date'] = datetime(2011, 7, 15, 21)
Because this is a naive ``datetime`` it will be interpreted as a UTC
timestamp, and the resulting value will have a timezone of ``-0000``. Much
more useful is to use the :func:`~email.utils.localtime` function from the
:mod:`~email.utils` module::
msg['Date'] = utils.localtime()
This example sets the date header to the current time and date using
the current timezone offset.
.. class:: AddressHeader
Address headers are one of the most complex structured header types.
The ``AddressHeader`` class provides a generic interface to any address
header.
This header type provides the following additional attributes:
.. attribute:: groups
A tuple of :class:`.Group` objects encoding the
addresses and groups found in the header value. Addresses that are
not part of a group are represented in this list as single-address
``Groups`` whose :attr:`~.Group.display_name` is ``None``.
.. attribute:: addresses
A tuple of :class:`.Address` objects encoding all
of the individual addresses from the header value. If the header value
contains any groups, the individual addresses from the group are included
in the list at the point where the group occurs in the value (that is,
the list of addresses is "flattened" into a one dimensional list).
The ``decoded`` value of the header will have all encoded words decoded to
unicode. :class:`~encodings.idna` encoded domain names are also decoded to
unicode. The ``decoded`` value is set by :attr:`~str.join`\ ing the
:class:`str` value of the elements of the ``groups`` attribute with ``',
'``.
A list of :class:`.Address` and :class:`.Group` objects in any combination
may be used to set the value of an address header. ``Group`` objects whose
``display_name`` is ``None`` will be interpreted as single addresses, which
allows an address list to be copied with groups intact by using the list
obtained from the ``groups`` attribute of the source header.
.. class:: SingleAddressHeader
A subclass of :class:`.AddressHeader` that adds one
additional attribute:
.. attribute:: address
The single address encoded by the header value. If the header value
actually contains more than one address (which would be a violation of
the RFC under the default :mod:`~email.policy`), accessing this attribute
will result in a :exc:`ValueError`.
Many of the above classes also have a ``Unique`` variant (for example,
``UniqueUnstructuredHeader``). The only difference is that in the ``Unique``
variant, :attr:`~.BaseHeader.max_count` is set to 1.
.. class:: MIMEVersionHeader
There is really only one valid value for the :mailheader:`MIME-Version`
header, and that is ``1.0``. For future proofing, this header class
supports other valid version numbers. If a version number has a valid value
per :rfc:`2045`, then the header object will have non-``None`` values for
the following attributes:
.. attribute:: version
The version number as a string, with any whitespace and/or comments
removed.
.. attribute:: major
The major version number as an integer
.. attribute:: minor
The minor version number as an integer
.. class:: ParameterizedMIMEHeader
MIME headers all start with the prefix 'Content-'. Each specific header has
a certain value, described under the class for that header. Some can
also take a list of supplemental parameters, which have a common format.
This class serves as a base for all the MIME headers that take parameters.
.. attribute:: params
A dictionary mapping parameter names to parameter values.
.. class:: ContentTypeHeader
A :class:`ParameterizedMIMEHeader` class that handles the
:mailheader:`Content-Type` header.
.. attribute:: content_type
The content type string, in the form ``maintype/subtype``.
.. attribute:: maintype
.. attribute:: subtype
.. class:: ContentDispositionHeader
A :class:`ParameterizedMIMEHeader` class that handles the
:mailheader:`Content-Disposition` header.
.. attribute:: content_disposition
``inline`` and ``attachment`` are the only valid values in common use.
.. class:: ContentTransferEncoding
Handles the :mailheader:`Content-Transfer-Encoding` header.
.. attribute:: cte
Valid values are ``7bit``, ``8bit``, ``base64``, and
``quoted-printable``. See :rfc:`2045` for more information.
.. class:: HeaderRegistry(base_class=BaseHeader, \
default_class=UnstructuredHeader, \
use_default_map=True)
This is the factory used by :class:`~email.policy.EmailPolicy` by default.
``HeaderRegistry`` builds the class used to create a header instance
dynamically, using *base_class* and a specialized class retrieved from a
registry that it holds. When a given header name does not appear in the
registry, the class specified by *default_class* is used as the specialized
class. When *use_default_map* is ``True`` (the default), the standard
mapping of header names to classes is copied in to the registry during
initialization. *base_class* is always the last class in the generated
class's ``__bases__`` list.
The default mappings are:
:subject: UniqueUnstructuredHeader
:date: UniqueDateHeader
:resent-date: DateHeader
:orig-date: UniqueDateHeader
:sender: UniqueSingleAddressHeader
:resent-sender: SingleAddressHeader
:to: UniqueAddressHeader
:resent-to: AddressHeader
:cc: UniqueAddressHeader
:resent-cc: AddressHeader
:bcc: UniqueAddressHeader
:resent-bcc: AddressHeader
:from: UniqueAddressHeader
:resent-from: AddressHeader
:reply-to: UniqueAddressHeader
:mime-version: MIMEVersionHeader
:content-type: ContentTypeHeader
:content-disposition: ContentDispositionHeader
:content-transfer-encoding: ContentTransferEncodingHeader
:message-id: MessageIDHeader
``HeaderRegistry`` has the following methods:
.. method:: map_to_type(self, name, cls)
*name* is the name of the header to be mapped. It will be converted to
lower case in the registry. *cls* is the specialized class to be used,
along with *base_class*, to create the class used to instantiate headers
that match *name*.
.. method:: __getitem__(name)
Construct and return a class to handle creating a *name* header.
.. method:: __call__(name, value)
Retrieves the specialized header associated with *name* from the
registry (using *default_class* if *name* does not appear in the
registry) and composes it with *base_class* to produce a class,
calls the constructed class's constructor, passing it the same
argument list, and finally returns the class instance created thereby.
The following classes are the classes used to represent data parsed from
structured headers and can, in general, be used by an application program to
construct structured values to assign to specific headers.
.. class:: Address(display_name='', username='', domain='', addr_spec=None)
The class used to represent an email address. The general form of an
address is::
[display_name] <username@domain>
or::
username@domain
where each part must conform to specific syntax rules spelled out in
:rfc:`5322`.
As a convenience *addr_spec* can be specified instead of *username* and
*domain*, in which case *username* and *domain* will be parsed from the
*addr_spec*. An *addr_spec* must be a properly RFC quoted string; if it is
not ``Address`` will raise an error. Unicode characters are allowed and
will be property encoded when serialized. However, per the RFCs, unicode is
*not* allowed in the username portion of the address.
.. attribute:: display_name
The display name portion of the address, if any, with all quoting
removed. If the address does not have a display name, this attribute
will be an empty string.
.. attribute:: username
The ``username`` portion of the address, with all quoting removed.
.. attribute:: domain
The ``domain`` portion of the address.
.. attribute:: addr_spec
The ``username@domain`` portion of the address, correctly quoted
for use as a bare address (the second form shown above). This
attribute is not mutable.
.. method:: __str__()
The ``str`` value of the object is the address quoted according to
:rfc:`5322` rules, but with no Content Transfer Encoding of any non-ASCII
characters.
To support SMTP (:rfc:`5321`), ``Address`` handles one special case: if
``username`` and ``domain`` are both the empty string (or ``None``), then
the string value of the ``Address`` is ``<>``.
.. class:: Group(display_name=None, addresses=None)
The class used to represent an address group. The general form of an
address group is::
display_name: [address-list];
As a convenience for processing lists of addresses that consist of a mixture
of groups and single addresses, a ``Group`` may also be used to represent
single addresses that are not part of a group by setting *display_name* to
``None`` and providing a list of the single address as *addresses*.
.. attribute:: display_name
The ``display_name`` of the group. If it is ``None`` and there is
exactly one ``Address`` in ``addresses``, then the ``Group`` represents a
single address that is not in a group.
.. attribute:: addresses
A possibly empty tuple of :class:`.Address` objects representing the
addresses in the group.
.. method:: __str__()
The ``str`` value of a ``Group`` is formatted according to :rfc:`5322`,
but with no Content Transfer Encoding of any non-ASCII characters. If
``display_name`` is none and there is a single ``Address`` in the
``addresses`` list, the ``str`` value will be the same as the ``str`` of
that single ``Address``.
.. rubric:: Footnotes
.. [1] Originally added in 3.3 as a :term:`provisional module <provisional
package>`

83
web/python-docs/_sources/library/email.iterators.rst.txt Normal file
View File

@@ -0,0 +1,83 @@
:mod:`email.iterators`: Iterators
---------------------------------
.. module:: email.iterators
:synopsis: Iterate over a message object tree.
**Source code:** :source:`Lib/email/iterators.py`
--------------
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=False)
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='text', subtype=None)
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=None, level=0, include_default=False)
Prints an indented representation of the content types of the message object
structure. For example:
.. testsetup::
import email
from email.iterators import _structure
somefile = open('../Lib/test/test_email/data/msg_02.txt')
.. doctest::
>>> 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
.. testcleanup::
somefile.close()
Optional *fp* is a file-like object to print the output to. It must be
suitable for Python's :func:`print` function. *level* is used internally.
*include_default*, if true, prints the default type as well.

751
web/python-docs/_sources/library/email.message.rst.txt Normal file
View File

@@ -0,0 +1,751 @@
:mod:`email.message`: Representing an email message
---------------------------------------------------
.. module:: email.message
:synopsis: The base class representing email messages.
.. moduleauthor:: R. David Murray <rdmurray@bitdance.com>
.. sectionauthor:: R. David Murray <rdmurray@bitdance.com>,
Barry A. Warsaw <barry@python.org>
**Source code:** :source:`Lib/email/message.py`
--------------
.. versionadded:: 3.6 [1]_
The central class in the :mod:`email` package is the :class:`EmailMessage`
class, imported from the :mod:`email.message` module. It is the base class for
the :mod:`email` object model. :class:`EmailMessage` provides the core
functionality for setting and querying header fields, for accessing message
bodies, and for creating or modifying structured messages.
An email message consists of *headers* and a *payload* (which is also referred
to as the *content*). Headers are :rfc:`5322` or :rfc:`6532` 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. The payload may be a
simple text message, or a binary object, or a structured sequence of
sub-messages each with their own set of headers and their own payload. The
latter type of payload is indicated by the message having a MIME type such as
:mimetype:`multipart/\*` or :mimetype:`message/rfc822`.
The conceptual model provided by an :class:`EmailMessage` object is that of an
ordered dictionary of headers coupled with a *payload* that represents the
:rfc:`5322` body of the message, which might be a list of sub-``EmailMessage``
objects. In addition to the normal dictionary methods for accessing the header
names and values, there are methods for accessing specialized information from
the headers (for example the MIME content type), for operating on the payload,
for generating a serialized version of the message, and for recursively walking
over the object tree.
The :class:`EmailMessage` dictionary-like interface is indexed by the header
names, which must be ASCII values. The values of the dictionary are strings
with some extra methods. Headers are stored and returned in case-preserving
form, but field names are matched case-insensitively. Unlike a real dict,
there is an ordering to the keys, and there can be duplicate keys. Additional
methods are provided for working with headers that have duplicate keys.
The *payload* is either a string or bytes object, in the case of simple message
objects, or a list of :class:`EmailMessage` objects, for MIME container
documents such as :mimetype:`multipart/\*` and :mimetype:`message/rfc822`
message objects.
.. class:: EmailMessage(policy=default)
If *policy* is specified use the rules it specifies to update and serialize
the representation of the message. If *policy* is not set, use the
:class:`~email.policy.default` policy, which follows the rules of the email
RFCs except for line endings (instead of the RFC mandated ``\r\n``, it uses
the Python standard ``\n`` line endings). For more information see the
:mod:`~email.policy` documentation.
.. method:: as_string(unixfrom=False, maxheaderlen=None, policy=None)
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``. For backward compatibility
with the base :class:`~email.message.Message` class *maxheaderlen* is
accepted, but defaults to ``None``, which means that by default the line
length is controlled by the
:attr:`~email.policy.EmailPolicy.max_line_length` of the policy. The
*policy* argument may be used to override the default policy obtained
from the message instance. This can be used to control some of the
formatting produced by the method, since the specified *policy* will be
passed to the :class:`~email.generator.Generator`.
Flattening the message may trigger changes to the :class:`EmailMessage`
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 be the
most useful way to serialize messages in your application, especially if
you are dealing with multiple messages. See
:class:`email.generator.Generator` for a more flexible API for
serializing messages. Note also that this method is restricted to
producing messages serialized as "7 bit clean" when
:attr:`~email.policy.EmailPolicy.utf8` is ``False``, which is the default.
.. versionchanged:: 3.6 the default behavior when *maxheaderlen*
is not specified was changed from defaulting to 0 to defaulting
to the value of *max_line_length* from the policy.
.. method:: __str__()
Equivalent to ``as_string(policy=self.policy.clone(utf8=True))``. Allows
``str(msg)`` to produce a string containing the serialized message in a
readable format.
.. versionchanged:: 3.4 the method was changed to use ``utf8=True``,
thus producing an :rfc:`6531`-like message representation, instead of
being a direct alias for :meth:`as_string`.
.. method:: as_bytes(unixfrom=False, policy=None)
Return the entire message flattened as a bytes object. When optional
*unixfrom* is true, the envelope header is included in the returned
string. *unixfrom* defaults to ``False``. The *policy* argument may be
used to override the default policy obtained from the message instance.
This can be used to control some of the formatting produced by the
method, since the specified *policy* will be passed to the
:class:`~email.generator.BytesGenerator`.
Flattening the message may trigger changes to the :class:`EmailMessage`
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 be the
most useful way to serialize messages in your application, especially if
you are dealing with multiple messages. See
:class:`email.generator.BytesGenerator` for a more flexible API for
serializing messages.
.. method:: __bytes__()
Equivalent to :meth:`.as_bytes()`. Allows ``bytes(msg)`` to produce a
bytes object containing the serialized message.
.. method:: is_multipart()
Return ``True`` if the message's payload is a list of
sub-\ :class:`EmailMessage` objects, otherwise return ``False``. When
:meth:`is_multipart` returns ``False``, the payload should be a string
object (which might be a CTE encoded binary payload). Note that
:meth:`is_multipart` returning ``True`` does not necessarily mean that
"msg.get_content_maintype() == 'multipart'" will return the ``True``.
For example, ``is_multipart`` will return ``True`` when the
:class:`EmailMessage` is of type ``message/rfc822``.
.. method:: set_unixfrom(unixfrom)
Set the message's envelope header to *unixfrom*, which should be a
string. (See :class:`~mailbox.mboxMessage` for a brief description of
this header.)
.. method:: get_unixfrom()
Return the message's envelope header. Defaults to ``None`` if the
envelope header was never set.
The following methods implement the mapping-like interface for accessing the
message's 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 an :class:`EmailMessage`
object, headers are always returned in the order they appeared in the
original message, or in which they were added to the message later. Any
header deleted and then re-added is always appended to the end of the
header list.
These semantic differences are intentional and are biased toward
convenience in the most common use cases.
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 without regard to case and *name* does not include the trailing
colon. Used for the ``in`` operator. For example::
if 'message-id' in myMessage:
print('Message-ID:', myMessage['message-id'])
.. method:: __getitem__(name)
Return the value of the named header field. *name* does 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 headers named *name*.
Using the standard (non-``compat32``) policies, the returned value is an
instance of a subclass of :class:`email.headerregistry.BaseHeader`.
.. 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 headers.
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!'
If the :mod:`policy` defines certain headers to be unique (as the standard
policies do), this method may raise a :exc:`ValueError` when an attempt
is made to assign a value to such a header when one already exists. This
behavior is intentional for consistency's sake, but do not depend on it
as we may choose to make such assignments do an automatic deletion of the
existing header in the future.
.. 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:: 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=None)
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 (*failobj* defaults to ``None``).
Here are some additional useful header related methods:
.. method:: get_all(name, failobj=None)
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, the charset and language may
be explicitly controlled by specifying the value 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. If a three tuple is not passed and the value contains
non-ASCII characters, it is automatically encoded in :rfc:`2231` format
using a ``CHARSET`` of ``utf-8`` and a ``LANGUAGE`` of ``None``.
Here is 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 of the extended interface with non-ASCII characters::
msg.add_header('Content-Disposition', 'attachment',
filename=('iso-8859-1', '', 'Fußballer.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 of the
original header. If no matching header is found, raise a
:exc:`KeyError`.
.. method:: get_content_type()
Return the message's content type, coerced to lower case of the form
:mimetype:`maintype/subtype`. If there is no :mailheader:`Content-Type`
header in the message return the value returned by
:meth:`get_default_type`. If the :mailheader:`Content-Type` header is
invalid, return ``text/plain``.
(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`.)
.. 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`.
.. 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`.
.. 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`.
.. 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, so it only affects the return value of
the ``get_content_type`` methods when no :mailheader:`Content-Type`
header is present in the message.
.. method:: set_param(param, value, header='Content-Type', requote=True, \
charset=None, language='', replace=False)
Set a parameter in the :mailheader:`Content-Type` header. If the
parameter already exists in the header, replace its value with *value*.
When *header* is ``Content-Type`` (the default) and the header does not
yet exist in the message, add it, set its value to
:mimetype:`text/plain`, and append the new parameter value. Optional
*header* specifies an alternative header to :mailheader:`Content-Type`.
If the value contains non-ASCII characters, the charset and language may
be explicitly specified using the optional *charset* and *language*
parameters. Optional *language* specifies the :rfc:`2231` language,
defaulting to the empty string. Both *charset* and *language* should be
strings. The default is to use the ``utf8`` *charset* and ``None`` for
the *language*.
If *replace* is ``False`` (the default) the header is moved to the
end of the list of headers. If *replace* is ``True``, the header
will be updated in place.
Use of the *requote* parameter with :class:`EmailMessage` objects is
deprecated.
Note that existing parameter values of headers may be accessed through
the :attr:`~email.headerregistry.BaseHeader.params` attribute of the
header value (for example, ``msg['Content-Type'].params['charset']``).
.. versionchanged:: 3.4 ``replace`` keyword was added.
.. method:: del_param(param, header='content-type', requote=True)
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. Optional *header* specifies an alternative to
:mailheader:`Content-Type`.
Use of the *requote* parameter with :class:`EmailMessage` objects is
deprecated.
.. method:: get_filename(failobj=None)
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=None)
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 from 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.
.. method:: get_content_charset(failobj=None)
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.
.. method:: get_charsets(failobj=None)
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. 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:: is_attachment
Return ``True`` if there is a :mailheader:`Content-Disposition` header
and its (case insensitive) value is ``attachment``, ``False`` otherwise.
.. versionchanged:: 3.4.2
is_attachment is now a method instead of a property, for consistency
with :meth:`~email.message.Message.is_multipart`.
.. method:: get_content_disposition()
Return the lowercased value (without parameters) of the message's
:mailheader:`Content-Disposition` header if it has one, or ``None``. The
possible values for this method are *inline*, *attachment* or ``None``
if the message follows :rfc:`2183`.
.. versionadded:: 3.5
The following methods relate to interrogating and manipulating the content
(payload) of the message.
.. 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:
.. testsetup::
from email import message_from_binary_file
with open('../Lib/test/test_email/data/msg_16.txt', 'rb') as f:
msg = message_from_binary_file(f)
.. doctest::
>>> for part in msg.walk():
... print(part.get_content_type())
multipart/report
text/plain
message/delivery-status
text/plain
text/plain
message/rfc822
text/plain
``walk`` iterates over the subparts of any part where
:meth:`is_multipart` returns ``True``, even though
``msg.get_content_maintype() == 'multipart'`` may return ``False``. We
can see this in our example by making use of the ``_structure`` debug
helper function:
.. doctest::
>>> from email.iterators import _structure
>>> for part in msg.walk():
... print(part.get_content_maintype() == 'multipart',
... part.is_multipart())
True True
False False
False True
False False
False False
False True
False False
>>> _structure(msg)
multipart/report
text/plain
message/delivery-status
text/plain
text/plain
message/rfc822
text/plain
Here the ``message`` parts are not ``multiparts``, but they do contain
subparts. ``is_multipart()`` returns ``True`` and ``walk`` descends
into the subparts.
.. method:: get_body(preferencelist=('related', 'html', 'plain'))
Return the MIME part that is the best candidate to be the "body" of the
message.
*preferencelist* must be a sequence of strings from the set ``related``,
``html``, and ``plain``, and indicates the order of preference for the
content type of the part returned.
Start looking for candidate matches with the object on which the
``get_body`` method is called.
If ``related`` is not included in *preferencelist*, consider the root
part (or subpart of the root part) of any related encountered as a
candidate if the (sub-)part matches a preference.
When encountering a ``multipart/related``, check the ``start`` parameter
and if a part with a matching :mailheader:`Content-ID` is found, consider
only it when looking for candidate matches. Otherwise consider only the
first (default root) part of the ``multipart/related``.
If a part has a :mailheader:`Content-Disposition` header, only consider
the part a candidate match if the value of the header is ``inline``.
If none of the candidates matches any of the preferences in
*preferencelist*, return ``None``.
Notes: (1) For most applications the only *preferencelist* combinations
that really make sense are ``('plain',)``, ``('html', 'plain')``, and the
default ``('related', 'html', 'plain')``. (2) Because matching starts
with the object on which ``get_body`` is called, calling ``get_body`` on
a ``multipart/related`` will return the object itself unless
*preferencelist* has a non-default value. (3) Messages (or message parts)
that do not specify a :mailheader:`Content-Type` or whose
:mailheader:`Content-Type` header is invalid will be treated as if they
are of type ``text/plain``, which may occasionally cause ``get_body`` to
return unexpected results.
.. method:: iter_attachments()
Return an iterator over all of the immediate sub-parts of the message
that are not candidate "body" parts. That is, skip the first occurrence
of each of ``text/plain``, ``text/html``, ``multipart/related``, or
``multipart/alternative`` (unless they are explicitly marked as
attachments via :mailheader:`Content-Disposition: attachment`), and
return all remaining parts. When applied directly to a
``multipart/related``, return an iterator over the all the related parts
except the root part (ie: the part pointed to by the ``start`` parameter,
or the first part if there is no ``start`` parameter or the ``start``
parameter doesn't match the :mailheader:`Content-ID` of any of the
parts). When applied directly to a ``multipart/alternative`` or a
non-``multipart``, return an empty iterator.
.. method:: iter_parts()
Return an iterator over all of the immediate sub-parts of the message,
which will be empty for a non-``multipart``. (See also
:meth:`~email.message.EmailMessage.walk`.)
.. method:: get_content(*args, content_manager=None, **kw)
Call the :meth:`~email.contentmanager.ContentManager.get_content` method
of the *content_manager*, passing self as the message object, and passing
along any other arguments or keywords as additional arguments. If
*content_manager* is not specified, use the ``content_manager`` specified
by the current :mod:`~email.policy`.
.. method:: set_content(*args, content_manager=None, **kw)
Call the :meth:`~email.contentmanager.ContentManager.set_content` method
of the *content_manager*, passing self as the message object, and passing
along any other arguments or keywords as additional arguments. If
*content_manager* is not specified, use the ``content_manager`` specified
by the current :mod:`~email.policy`.
.. method:: make_related(boundary=None)
Convert a non-``multipart`` message into a ``multipart/related`` message,
moving any existing :mailheader:`Content-` headers and payload into a
(new) first part of the ``multipart``. If *boundary* is specified, use
it as the boundary string in the multipart, otherwise leave the boundary
to be automatically created when it is needed (for example, when the
message is serialized).
.. method:: make_alternative(boundary=None)
Convert a non-``multipart`` or a ``multipart/related`` into a
``multipart/alternative``, moving any existing :mailheader:`Content-`
headers and payload into a (new) first part of the ``multipart``. If
*boundary* is specified, use it as the boundary string in the multipart,
otherwise leave the boundary to be automatically created when it is
needed (for example, when the message is serialized).
.. method:: make_mixed(boundary=None)
Convert a non-``multipart``, a ``multipart/related``, or a
``multipart-alternative`` into a ``multipart/mixed``, moving any existing
:mailheader:`Content-` headers and payload into a (new) first part of the
``multipart``. If *boundary* is specified, use it as the boundary string
in the multipart, otherwise leave the boundary to be automatically
created when it is needed (for example, when the message is serialized).
.. method:: add_related(*args, content_manager=None, **kw)
If the message is a ``multipart/related``, create a new message
object, pass all of the arguments to its :meth:`set_content` method,
and :meth:`~email.message.Message.attach` it to the ``multipart``. If
the message is a non-``multipart``, call :meth:`make_related` and then
proceed as above. If the message is any other type of ``multipart``,
raise a :exc:`TypeError`. If *content_manager* is not specified, use
the ``content_manager`` specified by the current :mod:`~email.policy`.
If the added part has no :mailheader:`Content-Disposition` header,
add one with the value ``inline``.
.. method:: add_alternative(*args, content_manager=None, **kw)
If the message is a ``multipart/alternative``, create a new message
object, pass all of the arguments to its :meth:`set_content` method, and
:meth:`~email.message.Message.attach` it to the ``multipart``. If the
message is a non-``multipart`` or ``multipart/related``, call
:meth:`make_alternative` and then proceed as above. If the message is
any other type of ``multipart``, raise a :exc:`TypeError`. If
*content_manager* is not specified, use the ``content_manager`` specified
by the current :mod:`~email.policy`.
.. method:: add_attachment(*args, content_manager=None, **kw)
If the message is a ``multipart/mixed``, create a new message object,
pass all of the arguments to its :meth:`set_content` method, and
:meth:`~email.message.Message.attach` it to the ``multipart``. If the
message is a non-``multipart``, ``multipart/related``, or
``multipart/alternative``, call :meth:`make_mixed` and then proceed as
above. If *content_manager* is not specified, use the ``content_manager``
specified by the current :mod:`~email.policy`. If the added part
has no :mailheader:`Content-Disposition` header, add one with the value
``attachment``. This method can be used both for explicit attachments
(:mailheader:`Content-Disposition: attachment`) and ``inline`` attachments
(:mailheader:`Content-Disposition: inline`), by passing appropriate
options to the ``content_manager``.
.. method:: clear()
Remove the payload and all of the headers.
.. method:: clear_content()
Remove the payload and all of the :exc:`Content-` headers, leaving
all other headers intact and in their original order.
:class:`EmailMessage` objects have the following instance attributes:
.. 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. As with the :attr:`~EmailMessage.preamble`,
if there is no epilog text this attribute will be ``None``.
.. 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.
.. class:: MIMEPart(policy=default)
This class represents a subpart of a MIME message. It is identical to
:class:`EmailMessage`, except that no :mailheader:`MIME-Version` headers are
added when :meth:`~EmailMessage.set_content` is called, since sub-parts do
not need their own :mailheader:`MIME-Version` headers.
.. rubric:: Footnotes
.. [1] Originally added in 3.4 as a :term:`provisional module <provisional
package>`. Docs for legacy message class moved to
:ref:`compat32_message`.

259
web/python-docs/_sources/library/email.mime.rst.txt Normal file
View File

@@ -0,0 +1,259 @@
:mod:`email.mime`: Creating email and MIME objects from scratch
---------------------------------------------------------------
.. module:: email.mime
:synopsis: Build MIME messages.
**Source code:** :source:`Lib/email/mime/`
--------------
This module is part of the legacy (``Compat32``) email API. Its functionality
is partially replaced by the :mod:`~email.contentmanager` in the new API, but
in certain applications these classes may still be useful, even in non-legacy
code.
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, *, policy=compat32, **_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>`.
If *policy* is specified, (defaults to the
:class:`compat32 <email.policy.Compat32>` policy) it will be passed to
:class:`~email.message.Message`.
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``).
.. versionchanged:: 3.6
Added *policy* keyword-only parameter.
.. 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.
.. currentmodule:: email.mime.multipart
.. class:: MIMEMultipart(_subtype='mixed', boundary=None, _subparts=None, \
*, policy=compat32, **_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.
Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`.
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.
.. versionchanged:: 3.6
Added *policy* keyword-only parameter.
.. currentmodule:: email.mime.application
.. class:: MIMEApplication(_data, _subtype='octet-stream', \
_encoder=email.encoders.encode_base64, \
*, policy=compat32, **_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.
Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`.
*_params* are passed straight through to the base class constructor.
.. versionchanged:: 3.6
Added *policy* keyword-only parameter.
.. currentmodule:: email.mime.audio
.. class:: MIMEAudio(_audiodata, _subtype=None, \
_encoder=email.encoders.encode_base64, \
*, policy=compat32, **_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*
argument. 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.
Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`.
*_params* are passed straight through to the base class constructor.
.. versionchanged:: 3.6
Added *policy* keyword-only parameter.
.. currentmodule:: email.mime.image
.. class:: MIMEImage(_imagedata, _subtype=None, \
_encoder=email.encoders.encode_base64, \
*, policy=compat32, **_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*
argument. 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.
Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`.
*_params* are passed straight through to the :class:`~email.mime.base.MIMEBase`
constructor.
.. versionchanged:: 3.6
Added *policy* keyword-only parameter.
.. currentmodule:: email.mime.message
.. class:: MIMEMessage(_msg, _subtype='rfc822', *, policy=compat32)
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`.
Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`.
.. versionchanged:: 3.6
Added *policy* keyword-only parameter.
.. currentmodule:: email.mime.text
.. class:: MIMEText(_text, _subtype='plain', _charset=None, *, policy=compat32)
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 an argument to the
:class:`~email.mime.nonmultipart.MIMENonMultipart` constructor; it defaults
to ``us-ascii`` if the string contains only ``ascii`` code points, and
``utf-8`` otherwise. The *_charset* parameter accepts either a string or a
:class:`~email.charset.Charset` instance.
Unless the *_charset* argument 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).
Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`.
.. versionchanged:: 3.5
*_charset* also accepts :class:`~email.charset.Charset` instances.
.. versionchanged:: 3.6
Added *policy* keyword-only parameter.

320
web/python-docs/_sources/library/email.parser.rst.txt Normal file
View File

@@ -0,0 +1,320 @@
:mod:`email.parser`: Parsing email messages
-------------------------------------------
.. module:: email.parser
:synopsis: Parse flat text email messages to produce a message object structure.
**Source code:** :source:`Lib/email/parser.py`
--------------
Message object structures can be created in one of two ways: they can be
created from whole cloth by creating an :class:`~email.message.EmailMessage`
object, adding headers using the dictionary interface, and adding payload(s)
using :meth:`~email.message.EmailMessage.set_content` and related methods, or
they can be created by parsing a serialized 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
bytes, string or file object, and the parser will return to you the root
:class:`~email.message.EmailMessage` 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.EmailMessage.is_multipart`
method, and the subparts can be accessed via the payload manipulation methods,
such as :meth:`~email.message.EmailMessage.get_body`,
:meth:`~email.message.EmailMessage.iter_parts`, and
:meth:`~email.message.EmailMessage.walk`.
There are actually two parser interfaces available for use, the :class:`Parser`
API and the incremental :class:`FeedParser` API. The :class:`Parser` API is
most useful if you have the entire text of the message in memory, or if the
entire message lives in a file on the file system. :class:`FeedParser` is more
appropriate when you are reading the message from a stream which might block
waiting for more input (such as 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. All of the logic that
connects the :mod:`email` package's bundled parser and the
:class:`~email.message.EmailMessage` class is embodied in the :mod:`policy`
class, so a custom parser can create message object trees any way it finds
necessary by implementing custom versions of the appropriate :mod:`policy`
methods.
FeedParser API
^^^^^^^^^^^^^^
The :class:`BytesFeedParser`, 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 (such as a socket). The :class:`BytesFeedParser` can of
course be used to parse an email message fully contained in a :term:`bytes-like
object`, string, or file, but the :class:`BytesParser` API may be more
convenient for such use cases. The semantics and results of the two parser
APIs are identical.
The :class:`BytesFeedParser`'s API is simple; you create an instance, feed it a
bunch of bytes until there's no more to feed it, then close the parser to
retrieve the root message object. The :class:`BytesFeedParser` 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
:attr:`~email.message.EmailMessage.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:`BytesFeedParser`:
.. class:: BytesFeedParser(_factory=None, *, policy=policy.compat32)
Create a :class:`BytesFeedParser` instance. Optional *_factory* is a
no-argument callable; if not specified use the
:attr:`~email.policy.Policy.message_factory` from the *policy*. Call
*_factory* whenever a new message object is needed.
If *policy* is specified use the rules it specifies to update the
representation of the message. If *policy* is not set, use the
:class:`compat32 <email.policy.Compat32>` policy, which maintains backward
compatibility with the Python 3.2 version of the email package and provides
:class:`~email.message.Message` as the default factory. All other policies
provide :class:`~email.message.EmailMessage` as the default *_factory*. For
more information on what else *policy* controls, see the
:mod:`~email.policy` documentation.
Note: **The policy keyword should always be specified**; The default will
change to :data:`email.policy.default` in a future version of Python.
.. versionadded:: 3.2
.. versionchanged:: 3.3 Added the *policy* keyword.
.. versionchanged:: 3.6 *_factory* defaults to the policy ``message_factory``.
.. method:: feed(data)
Feed the parser some more data. *data* should be a :term:`bytes-like
object` containing one or more lines. The lines can be partial and the
parser will stitch such partial lines together properly. The lines can
have any of the three common line endings: carriage return, newline, or
carriage return and newline (they can even be mixed).
.. method:: close()
Complete the parsing of all previously fed data and return the root
message object. It is undefined what happens if :meth:`~feed` is called
after this method has been called.
.. class:: FeedParser(_factory=None, *, policy=policy.compat32)
Works like :class:`BytesFeedParser` except that the input to the
:meth:`~BytesFeedParser.feed` method must be a string. This is of limited
utility, since the only way for such a message to be valid is for it to
contain only ASCII text or, if :attr:`~email.policy.Policy.utf8` is
``True``, no binary attachments.
.. versionchanged:: 3.3 Added the *policy* keyword.
Parser API
^^^^^^^^^^
The :class:`BytesParser` 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 :term:`bytes-like object` or file. The
:mod:`email.parser` module also provides :class:`Parser` for parsing strings,
and header-only parsers, :class:`BytesHeaderParser` and
:class:`HeaderParser`, which can be used if you're only interested in the
headers of the message. :class:`BytesHeaderParser` and :class:`HeaderParser`
can be much faster in these situations, since they do not attempt to parse the
message body, instead setting the payload to the raw body.
.. class:: BytesParser(_class=None, *, policy=policy.compat32)
Create a :class:`BytesParser` instance. The *_class* and *policy*
arguments have the same meaning and semantics as the *_factory*
and *policy* arguments of :class:`BytesFeedParser`.
Note: **The policy keyword should always be specified**; The default will
change to :data:`email.policy.default` in a future version of Python.
.. versionchanged:: 3.3
Removed the *strict* argument that was deprecated in 2.4. Added the
*policy* keyword.
.. versionchanged:: 3.6 *_class* defaults to the policy ``message_factory``.
.. method:: parse(fp, headersonly=False)
Read all the data from the binary file-like object *fp*, parse the
resulting bytes, and return the message object. *fp* must support
both the :meth:`~io.IOBase.readline` and the :meth:`~io.IOBase.read`
methods.
The bytes contained in *fp* must be formatted as a block of :rfc:`5322`
(or, if :attr:`~email.policy.Policy.utf8` is ``True``, :rfc:`6532`)
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, including subparts
with a :mailheader:`Content-Transfer-Encoding` of ``8bit``).
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.
.. method:: parsebytes(bytes, headersonly=False)
Similar to the :meth:`parse` method, except it takes a :term:`bytes-like
object` instead of a file-like object. Calling this method on a
:term:`bytes-like object` is equivalent to wrapping *bytes* in a
:class:`~io.BytesIO` instance first and calling :meth:`parse`.
Optional *headersonly* is as with the :meth:`parse` method.
.. versionadded:: 3.2
.. class:: BytesHeaderParser(_class=None, *, policy=policy.compat32)
Exactly like :class:`BytesParser`, except that *headersonly*
defaults to ``True``.
.. versionadded:: 3.3
.. class:: Parser(_class=None, *, policy=policy.compat32)
This class is parallel to :class:`BytesParser`, but handles string input.
.. versionchanged:: 3.3
Removed the *strict* argument. Added the *policy* keyword.
.. versionchanged:: 3.6 *_class* defaults to the policy ``message_factory``.
.. method:: parse(fp, headersonly=False)
Read all the data from the text-mode 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.
Other than the text mode requirement, this method operates like
:meth:`BytesParser.parse`.
.. method:: parsestr(text, headersonly=False)
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
equivalent to wrapping *text* in a :class:`~io.StringIO` instance first
and calling :meth:`parse`.
Optional *headersonly* is as with the :meth:`parse` method.
.. class:: HeaderParser(_class=None, *, policy=policy.compat32)
Exactly like :class:`Parser`, except that *headersonly*
defaults to ``True``.
Since creating a message object structure from a string or a file object is such
a common task, four functions are provided as a convenience. They are available
in the top-level :mod:`email` package namespace.
.. currentmodule:: email
.. function:: message_from_bytes(s, _class=None, *, policy=policy.compat32)
Return a message object structure from a :term:`bytes-like object`. This is
equivalent to ``BytesParser().parsebytes(s)``. Optional *_class* and
*policy* are interpreted as with the :class:`~email.parser.BytesParser` class
constructor.
.. versionadded:: 3.2
.. versionchanged:: 3.3
Removed the *strict* argument. Added the *policy* keyword.
.. function:: message_from_binary_file(fp, _class=None, *, \
policy=policy.compat32)
Return a message object structure tree from an open binary :term:`file
object`. This is equivalent to ``BytesParser().parse(fp)``. *_class* and
*policy* are interpreted as with the :class:`~email.parser.BytesParser` class
constructor.
.. versionadded:: 3.2
.. versionchanged:: 3.3
Removed the *strict* argument. Added the *policy* keyword.
.. function:: message_from_string(s, _class=None, *, policy=policy.compat32)
Return a message object structure from a string. This is equivalent to
``Parser().parsestr(s)``. *_class* and *policy* are interpreted as
with the :class:`~email.parser.Parser` class constructor.
.. versionchanged:: 3.3
Removed the *strict* argument. Added the *policy* keyword.
.. function:: message_from_file(fp, _class=None, *, policy=policy.compat32)
Return a message object structure tree from an open :term:`file object`.
This is equivalent to ``Parser().parse(fp)``. *_class* and *policy* are
interpreted as with the :class:`~email.parser.Parser` class constructor.
.. versionchanged:: 3.3
Removed the *strict* argument. Added the *policy* keyword.
.. versionchanged:: 3.6 *_class* defaults to the policy ``message_factory``.
Here's an example of how you might use :func:`message_from_bytes` at an
interactive Python prompt::
>>> import email
>>> msg = email.message_from_bytes(myBytes) # doctest: +SKIP
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.EmailMessage.is_multipart`, and
:meth:`~email.message.EmailMessage.iter_parts` will yield an empty list.
* 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.EmailMessage.is_multipart`, and
:meth:`~email.message.EmailMessage.iter_parts` will yield a list of subparts.
* Most messages with a content type of :mimetype:`message/\*` (such as
: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.EmailMessage.is_multipart` method will return ``True``.
The single element yielded by :meth:`~email.message.EmailMessage.iter_parts`
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.EmailMessage.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.

669
web/python-docs/_sources/library/email.policy.rst.txt Normal file
View File

@@ -0,0 +1,669 @@
:mod:`email.policy`: Policy Objects
-----------------------------------
.. module:: email.policy
:synopsis: Controlling the parsing and generating of messages
.. moduleauthor:: R. David Murray <rdmurray@bitdance.com>
.. sectionauthor:: R. David Murray <rdmurray@bitdance.com>
.. versionadded:: 3.3
**Source code:** :source:`Lib/email/policy.py`
--------------
The :mod:`email` package's prime focus is the handling of email messages as
described by the various email and MIME RFCs. However, the general format of
email messages (a block of header fields each consisting of a name followed by
a colon followed by a value, the whole block followed by a blank line and an
arbitrary 'body'), is a format that has found utility outside of the realm of
email. Some of these uses conform fairly closely to the main email RFCs, some
do not. Even when working with email, there are times when it is desirable to
break strict compliance with the RFCs, such as generating emails that
interoperate with email servers that do not themselves follow the standards, or
that implement extensions you want to use in ways that violate the
standards.
Policy objects give the email package the flexibility to handle all these
disparate use cases.
A :class:`Policy` object encapsulates a set of attributes and methods that
control the behavior of various components of the email package during use.
:class:`Policy` instances can be passed to various classes and methods in the
email package to alter the default behavior. The settable values and their
defaults are described below.
There is a default policy used by all classes in the email package. For all of
the :mod:`~email.parser` classes and the related convenience functions, and for
the :class:`~email.message.Message` class, this is the :class:`Compat32`
policy, via its corresponding pre-defined instance :const:`compat32`. This
policy provides for complete backward compatibility (in some cases, including
bug compatibility) with the pre-Python3.3 version of the email package.
This default value for the *policy* keyword to
:class:`~email.message.EmailMessage` is the :class:`EmailPolicy` policy, via
its pre-defined instance :data:`~default`.
When a :class:`~email.message.Message` or :class:`~email.message.EmailMessage`
object is created, it acquires a policy. If the message is created by a
:mod:`~email.parser`, a policy passed to the parser will be the policy used by
the message it creates. If the message is created by the program, then the
policy can be specified when it is created. When a message is passed to a
:mod:`~email.generator`, the generator uses the policy from the message by
default, but you can also pass a specific policy to the generator that will
override the one stored on the message object.
The default value for the *policy* keyword for the :mod:`email.parser` classes
and the parser convenience functions **will be changing** in a future version of
Python. Therefore you should **always specify explicitly which policy you want
to use** when calling any of the classes and functions described in the
:mod:`~email.parser` module.
The first part of this documentation covers the features of :class:`Policy`, an
:term:`abstract base class` that defines the features that are common to all
policy objects, including :const:`compat32`. This includes certain hook
methods that are called internally by the email package, which a custom policy
could override to obtain different behavior. The second part describes the
concrete classes :class:`EmailPolicy` and :class:`Compat32`, which implement
the hooks that provide the standard behavior and the backward compatible
behavior and features, respectively.
:class:`Policy` instances are immutable, but they can be cloned, accepting the
same keyword arguments as the class constructor and returning a new
:class:`Policy` instance that is a copy of the original but with the specified
attributes values changed.
As an example, the following code could be used to read an email message from a
file on disk and pass it to the system ``sendmail`` program on a Unix system:
.. testsetup::
from unittest import mock
mocker = mock.patch('subprocess.Popen')
m = mocker.start()
proc = mock.MagicMock()
m.return_value = proc
proc.stdin.close.return_value = None
mymsg = open('mymsg.txt', 'w')
mymsg.write('To: abc@xyz.com\n\n')
mymsg.flush()
.. doctest::
>>> from email import message_from_binary_file
>>> from email.generator import BytesGenerator
>>> from email import policy
>>> from subprocess import Popen, PIPE
>>> with open('mymsg.txt', 'rb') as f:
... msg = message_from_binary_file(f, policy=policy.default)
>>> p = Popen(['sendmail', msg['To'].addresses[0]], stdin=PIPE)
>>> g = BytesGenerator(p.stdin, policy=msg.policy.clone(linesep='\r\n'))
>>> g.flatten(msg)
>>> p.stdin.close()
>>> rc = p.wait()
.. testcleanup::
mymsg.close()
mocker.stop()
import os
os.remove('mymsg.txt')
Here we are telling :class:`~email.generator.BytesGenerator` to use the RFC
correct line separator characters when creating the binary string to feed into
``sendmail's`` ``stdin``, where the default policy would use ``\n`` line
separators.
Some email package methods accept a *policy* keyword argument, allowing the
policy to be overridden for that method. For example, the following code uses
the :meth:`~email.message.Message.as_bytes` method of the *msg* object from
the previous example and writes the message to a file using the native line
separators for the platform on which it is running::
>>> import os
>>> with open('converted.txt', 'wb') as f:
... f.write(msg.as_bytes(policy=msg.policy.clone(linesep=os.linesep)))
17
Policy objects can also be combined using the addition operator, producing a
policy object whose settings are a combination of the non-default values of the
summed objects::
>>> compat_SMTP = policy.compat32.clone(linesep='\r\n')
>>> compat_strict = policy.compat32.clone(raise_on_defect=True)
>>> compat_strict_SMTP = compat_SMTP + compat_strict
This operation is not commutative; that is, the order in which the objects are
added matters. To illustrate::
>>> policy100 = policy.compat32.clone(max_line_length=100)
>>> policy80 = policy.compat32.clone(max_line_length=80)
>>> apolicy = policy100 + policy80
>>> apolicy.max_line_length
80
>>> apolicy = policy80 + policy100
>>> apolicy.max_line_length
100
.. class:: Policy(**kw)
This is the :term:`abstract base class` for all policy classes. It provides
default implementations for a couple of trivial methods, as well as the
implementation of the immutability property, the :meth:`clone` method, and
the constructor semantics.
The constructor of a policy class can be passed various keyword arguments.
The arguments that may be specified are any non-method properties on this
class, plus any additional non-method properties on the concrete class. A
value specified in the constructor will override the default value for the
corresponding attribute.
This class defines the following properties, and thus values for the
following may be passed in the constructor of any policy class:
.. attribute:: max_line_length
The maximum length of any line in the serialized output, not counting the
end of line character(s). Default is 78, per :rfc:`5322`. A value of
``0`` or :const:`None` indicates that no line wrapping should be
done at all.
.. attribute:: linesep
The string to be used to terminate lines in serialized output. The
default is ``\n`` because that's the internal end-of-line discipline used
by Python, though ``\r\n`` is required by the RFCs.
.. attribute:: cte_type
Controls the type of Content Transfer Encodings that may be or are
required to be used. The possible values are:
.. tabularcolumns:: |l|L|
======== ===============================================================
``7bit`` all data must be "7 bit clean" (ASCII-only). This means that
where necessary data will be encoded using either
quoted-printable or base64 encoding.
``8bit`` data is not constrained to be 7 bit clean. Data in headers is
still required to be ASCII-only and so will be encoded (see
:meth:`fold_binary` and :attr:`~EmailPolicy.utf8` below for
exceptions), but body parts may use the ``8bit`` CTE.
======== ===============================================================
A ``cte_type`` value of ``8bit`` only works with ``BytesGenerator``, not
``Generator``, because strings cannot contain binary data. If a
``Generator`` is operating under a policy that specifies
``cte_type=8bit``, it will act as if ``cte_type`` is ``7bit``.
.. attribute:: raise_on_defect
If :const:`True`, any defects encountered will be raised as errors. If
:const:`False` (the default), defects will be passed to the
:meth:`register_defect` method.
.. attribute:: mangle_from_
If :const:`True`, lines starting with *"From "* in the body are
escaped by putting a ``>`` in front of them. This parameter is used when
the message is being serialized by a generator.
Default: :const:`False`.
.. versionadded:: 3.5
The *mangle_from_* parameter.
.. attribute:: message_factory
A factory function for constructing a new empty message object. Used
by the parser when building messages. Defaults to ``None``, in
which case :class:`~email.message.Message` is used.
.. versionadded:: 3.6
.. attribute:: verify_generated_headers
If ``True`` (the default), the generator will raise
:exc:`~email.errors.HeaderWriteError` instead of writing a header
that is improperly folded or delimited, such that it would
be parsed as multiple headers or joined with adjacent data.
Such headers can be generated by custom header classes or bugs
in the ``email`` module.
As it's a security feature, this defaults to ``True`` even in the
:class:`~email.policy.Compat32` policy.
For backwards compatible, but unsafe, behavior, it must be set to
``False`` explicitly.
.. versionadded:: 3.8.20
The following :class:`Policy` method is intended to be called by code using
the email library to create policy instances with custom settings:
.. method:: clone(**kw)
Return a new :class:`Policy` instance whose attributes have the same
values as the current instance, except where those attributes are
given new values by the keyword arguments.
The remaining :class:`Policy` methods are called by the email package code,
and are not intended to be called by an application using the email package.
A custom policy must implement all of these methods.
.. method:: handle_defect(obj, defect)
Handle a *defect* found on *obj*. When the email package calls this
method, *defect* will always be a subclass of
:class:`~email.errors.Defect`.
The default implementation checks the :attr:`raise_on_defect` flag. If
it is ``True``, *defect* is raised as an exception. If it is ``False``
(the default), *obj* and *defect* are passed to :meth:`register_defect`.
.. method:: register_defect(obj, defect)
Register a *defect* on *obj*. In the email package, *defect* will always
be a subclass of :class:`~email.errors.Defect`.
The default implementation calls the ``append`` method of the ``defects``
attribute of *obj*. When the email package calls :attr:`handle_defect`,
*obj* will normally have a ``defects`` attribute that has an ``append``
method. Custom object types used with the email package (for example,
custom ``Message`` objects) should also provide such an attribute,
otherwise defects in parsed messages will raise unexpected errors.
.. method:: header_max_count(name)
Return the maximum allowed number of headers named *name*.
Called when a header is added to an :class:`~email.message.EmailMessage`
or :class:`~email.message.Message` object. If the returned value is not
``0`` or ``None``, and there are already a number of headers with the
name *name* greater than or equal to the value returned, a
:exc:`ValueError` is raised.
Because the default behavior of ``Message.__setitem__`` is to append the
value to the list of headers, it is easy to create duplicate headers
without realizing it. This method allows certain headers to be limited
in the number of instances of that header that may be added to a
``Message`` programmatically. (The limit is not observed by the parser,
which will faithfully produce as many headers as exist in the message
being parsed.)
The default implementation returns ``None`` for all header names.
.. method:: header_source_parse(sourcelines)
The email package calls this method with a list of strings, each string
ending with the line separation characters found in the source being
parsed. The first line includes the field header name and separator.
All whitespace in the source is preserved. The method should return the
``(name, value)`` tuple that is to be stored in the ``Message`` to
represent the parsed header.
If an implementation wishes to retain compatibility with the existing
email package policies, *name* should be the case preserved name (all
characters up to the '``:``' separator), while *value* should be the
unfolded value (all line separator characters removed, but whitespace
kept intact), stripped of leading whitespace.
*sourcelines* may contain surrogateescaped binary data.
There is no default implementation
.. method:: header_store_parse(name, value)
The email package calls this method with the name and value provided by
the application program when the application program is modifying a
``Message`` programmatically (as opposed to a ``Message`` created by a
parser). The method should return the ``(name, value)`` tuple that is to
be stored in the ``Message`` to represent the header.
If an implementation wishes to retain compatibility with the existing
email package policies, the *name* and *value* should be strings or
string subclasses that do not change the content of the passed in
arguments.
There is no default implementation
.. method:: header_fetch_parse(name, value)
The email package calls this method with the *name* and *value* currently
stored in the ``Message`` when that header is requested by the
application program, and whatever the method returns is what is passed
back to the application as the value of the header being retrieved.
Note that there may be more than one header with the same name stored in
the ``Message``; the method is passed the specific name and value of the
header destined to be returned to the application.
*value* may contain surrogateescaped binary data. There should be no
surrogateescaped binary data in the value returned by the method.
There is no default implementation
.. method:: fold(name, value)
The email package calls this method with the *name* and *value* currently
stored in the ``Message`` for a given header. The method should return a
string that represents that header "folded" correctly (according to the
policy settings) by composing the *name* with the *value* and inserting
:attr:`linesep` characters at the appropriate places. See :rfc:`5322`
for a discussion of the rules for folding email headers.
*value* may contain surrogateescaped binary data. There should be no
surrogateescaped binary data in the string returned by the method.
.. method:: fold_binary(name, value)
The same as :meth:`fold`, except that the returned value should be a
bytes object rather than a string.
*value* may contain surrogateescaped binary data. These could be
converted back into binary data in the returned bytes object.
.. class:: EmailPolicy(**kw)
This concrete :class:`Policy` provides behavior that is intended to be fully
compliant with the current email RFCs. These include (but are not limited
to) :rfc:`5322`, :rfc:`2047`, and the current MIME RFCs.
This policy adds new header parsing and folding algorithms. Instead of
simple strings, headers are ``str`` subclasses with attributes that depend
on the type of the field. The parsing and folding algorithm fully implement
:rfc:`2047` and :rfc:`5322`.
The default value for the :attr:`~email.policy.Policy.message_factory`
attribute is :class:`~email.message.EmailMessage`.
In addition to the settable attributes listed above that apply to all
policies, this policy adds the following additional attributes:
.. versionadded:: 3.6 [1]_
.. attribute:: utf8
If ``False``, follow :rfc:`5322`, supporting non-ASCII characters in
headers by encoding them as "encoded words". If ``True``, follow
:rfc:`6532` and use ``utf-8`` encoding for headers. Messages
formatted in this way may be passed to SMTP servers that support
the ``SMTPUTF8`` extension (:rfc:`6531`).
.. attribute:: refold_source
If the value for a header in the ``Message`` object originated from a
:mod:`~email.parser` (as opposed to being set by a program), this
attribute indicates whether or not a generator should refold that value
when transforming the message back into serialized form. The possible
values are:
======== ===============================================================
``none`` all source values use original folding
``long`` source values that have any line that is longer than
``max_line_length`` will be refolded
``all`` all values are refolded.
======== ===============================================================
The default is ``long``.
.. attribute:: header_factory
A callable that takes two arguments, ``name`` and ``value``, where
``name`` is a header field name and ``value`` is an unfolded header field
value, and returns a string subclass that represents that header. A
default ``header_factory`` (see :mod:`~email.headerregistry`) is provided
that supports custom parsing for the various address and date :RFC:`5322`
header field types, and the major MIME header field stypes. Support for
additional custom parsing will be added in the future.
.. attribute:: content_manager
An object with at least two methods: get_content and set_content. When
the :meth:`~email.message.EmailMessage.get_content` or
:meth:`~email.message.EmailMessage.set_content` method of an
:class:`~email.message.EmailMessage` object is called, it calls the
corresponding method of this object, passing it the message object as its
first argument, and any arguments or keywords that were passed to it as
additional arguments. By default ``content_manager`` is set to
:data:`~email.contentmanager.raw_data_manager`.
.. versionadded:: 3.4
The class provides the following concrete implementations of the abstract
methods of :class:`Policy`:
.. method:: header_max_count(name)
Returns the value of the
:attr:`~email.headerregistry.BaseHeader.max_count` attribute of the
specialized class used to represent the header with the given name.
.. method:: header_source_parse(sourcelines)
The name is parsed as everything up to the '``:``' and returned
unmodified. The value is determined by stripping leading whitespace off
the remainder of the first line, joining all subsequent lines together,
and stripping any trailing carriage return or linefeed characters.
.. method:: header_store_parse(name, value)
The name is returned unchanged. If the input value has a ``name``
attribute and it matches *name* ignoring case, the value is returned
unchanged. Otherwise the *name* and *value* are passed to
``header_factory``, and the resulting header object is returned as
the value. In this case a ``ValueError`` is raised if the input value
contains CR or LF characters.
.. method:: header_fetch_parse(name, value)
If the value has a ``name`` attribute, it is returned to unmodified.
Otherwise the *name*, and the *value* with any CR or LF characters
removed, are passed to the ``header_factory``, and the resulting
header object is returned. Any surrogateescaped bytes get turned into
the unicode unknown-character glyph.
.. method:: fold(name, value)
Header folding is controlled by the :attr:`refold_source` policy setting.
A value is considered to be a 'source value' if and only if it does not
have a ``name`` attribute (having a ``name`` attribute means it is a
header object of some sort). If a source value needs to be refolded
according to the policy, it is converted into a header object by
passing the *name* and the *value* with any CR and LF characters removed
to the ``header_factory``. Folding of a header object is done by
calling its ``fold`` method with the current policy.
Source values are split into lines using :meth:`~str.splitlines`. If
the value is not to be refolded, the lines are rejoined using the
``linesep`` from the policy and returned. The exception is lines
containing non-ascii binary data. In that case the value is refolded
regardless of the ``refold_source`` setting, which causes the binary data
to be CTE encoded using the ``unknown-8bit`` charset.
.. method:: fold_binary(name, value)
The same as :meth:`fold` if :attr:`~Policy.cte_type` is ``7bit``, except
that the returned value is bytes.
If :attr:`~Policy.cte_type` is ``8bit``, non-ASCII binary data is
converted back
into bytes. Headers with binary data are not refolded, regardless of the
``refold_header`` setting, since there is no way to know whether the
binary data consists of single byte characters or multibyte characters.
The following instances of :class:`EmailPolicy` provide defaults suitable for
specific application domains. Note that in the future the behavior of these
instances (in particular the ``HTTP`` instance) may be adjusted to conform even
more closely to the RFCs relevant to their domains.
.. data:: default
An instance of ``EmailPolicy`` with all defaults unchanged. This policy
uses the standard Python ``\n`` line endings rather than the RFC-correct
``\r\n``.
.. data:: SMTP
Suitable for serializing messages in conformance with the email RFCs.
Like ``default``, but with ``linesep`` set to ``\r\n``, which is RFC
compliant.
.. data:: SMTPUTF8
The same as ``SMTP`` except that :attr:`~EmailPolicy.utf8` is ``True``.
Useful for serializing messages to a message store without using encoded
words in the headers. Should only be used for SMTP transmission if the
sender or recipient addresses have non-ASCII characters (the
:meth:`smtplib.SMTP.send_message` method handles this automatically).
.. data:: HTTP
Suitable for serializing headers with for use in HTTP traffic. Like
``SMTP`` except that ``max_line_length`` is set to ``None`` (unlimited).
.. data:: strict
Convenience instance. The same as ``default`` except that
``raise_on_defect`` is set to ``True``. This allows any policy to be made
strict by writing::
somepolicy + policy.strict
With all of these :class:`EmailPolicies <.EmailPolicy>`, the effective API of
the email package is changed from the Python 3.2 API in the following ways:
* Setting a header on a :class:`~email.message.Message` results in that
header being parsed and a header object created.
* Fetching a header value from a :class:`~email.message.Message` results
in that header being parsed and a header object created and
returned.
* Any header object, or any header that is refolded due to the
policy settings, is folded using an algorithm that fully implements the
RFC folding algorithms, including knowing where encoded words are required
and allowed.
From the application view, this means that any header obtained through the
:class:`~email.message.EmailMessage` is a header object with extra
attributes, whose string value is the fully decoded unicode value of the
header. Likewise, a header may be assigned a new value, or a new header
created, using a unicode string, and the policy will take care of converting
the unicode string into the correct RFC encoded form.
The header objects and their attributes are described in
:mod:`~email.headerregistry`.
.. class:: Compat32(**kw)
This concrete :class:`Policy` is the backward compatibility policy. It
replicates the behavior of the email package in Python 3.2. The
:mod:`~email.policy` module also defines an instance of this class,
:const:`compat32`, that is used as the default policy. Thus the default
behavior of the email package is to maintain compatibility with Python 3.2.
The following attributes have values that are different from the
:class:`Policy` default:
.. attribute:: mangle_from_
The default is ``True``.
The class provides the following concrete implementations of the
abstract methods of :class:`Policy`:
.. method:: header_source_parse(sourcelines)
The name is parsed as everything up to the '``:``' and returned
unmodified. The value is determined by stripping leading whitespace off
the remainder of the first line, joining all subsequent lines together,
and stripping any trailing carriage return or linefeed characters.
.. method:: header_store_parse(name, value)
The name and value are returned unmodified.
.. method:: header_fetch_parse(name, value)
If the value contains binary data, it is converted into a
:class:`~email.header.Header` object using the ``unknown-8bit`` charset.
Otherwise it is returned unmodified.
.. method:: fold(name, value)
Headers are folded using the :class:`~email.header.Header` folding
algorithm, which preserves existing line breaks in the value, and wraps
each resulting line to the ``max_line_length``. Non-ASCII binary data are
CTE encoded using the ``unknown-8bit`` charset.
.. method:: fold_binary(name, value)
Headers are folded using the :class:`~email.header.Header` folding
algorithm, which preserves existing line breaks in the value, and wraps
each resulting line to the ``max_line_length``. If ``cte_type`` is
``7bit``, non-ascii binary data is CTE encoded using the ``unknown-8bit``
charset. Otherwise the original source header is used, with its existing
line breaks and any (RFC invalid) binary data it may contain.
.. data:: compat32
An instance of :class:`Compat32`, providing backward compatibility with the
behavior of the email package in Python 3.2.
.. rubric:: Footnotes
.. [1] Originally added in 3.3 as a :term:`provisional feature <provisional
package>`.

152
web/python-docs/_sources/library/email.rst.txt Normal file
View File

@@ -0,0 +1,152 @@
:mod:`email` --- An email and MIME handling package
===================================================
.. module:: email
:synopsis: Package supporting the parsing, manipulating, and generating
email messages.
.. moduleauthor:: Barry A. Warsaw <barry@python.org>,
R. David Murray <rdmurray@bitdance.com>
.. sectionauthor:: R. David Murray <rdmurray@bitdance.com>
**Source code:** :source:`Lib/email/__init__.py`
--------------
The :mod:`email` package is a library for managing email messages. 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 :rfc:`5322` and :rfc:`6532`, as well as
such MIME-related RFCs as :rfc:`2045`, :rfc:`2046`, :rfc:`2047`, :rfc:`2183`,
and :rfc:`2231`.
The overall structure of the email package can be divided into three major
components, plus a fourth component that controls the behavior of the other
components.
The central component of the package is an "object model" that represents email
messages. An application interacts with the package primarily through the
object model interface defined in the :mod:`~email.message` sub-module. The
application can use this API to ask questions about an existing email, to
construct a new email, or to add or remove email subcomponents that themselves
use the same object model interface. That is, following the nature of email
messages and their MIME subcomponents, the email object model is a tree
structure of objects that all provide the :class:`~email.message.EmailMessage`
API.
The other two major components of the package are the :mod:`~email.parser` and
the :mod:`~email.generator`. The parser takes the serialized version of an
email message (a stream of bytes) and converts it into a tree of
:class:`~email.message.EmailMessage` objects. The generator takes an
:class:`~email.message.EmailMessage` and turns it back into a serialized byte
stream. (The parser and generator also handle streams of text characters, but
this usage is discouraged as it is too easy to end up with messages that are
not valid in one way or another.)
The control component is the :mod:`~email.policy` module. Every
:class:`~email.message.EmailMessage`, every :mod:`~email.generator`, and every
:mod:`~email.parser` has an associated :mod:`~email.policy` object that
controls its behavior. Usually an application only needs to specify the policy
when an :class:`~email.message.EmailMessage` is created, either by directly
instantiating an :class:`~email.message.EmailMessage` to create a new email,
or by parsing an input stream using a :mod:`~email.parser`. But the policy can
be changed when the message is serialized using a :mod:`~email.generator`.
This allows, for example, a generic email message to be parsed from disk, but
to serialize it using standard SMTP settings when sending it to an email
server.
The email package does its best to hide the details of the various governing
RFCs from the application. Conceptually the application should be able to
treat the email message as a structured tree of unicode text and binary
attachments, without having to worry about how these are represented when
serialized. In practice, however, it is often necessary to be aware of at
least some of the rules governing MIME messages and their structure,
specifically the names and nature of the MIME "content types" and how they
identify multipart documents. For the most part this knowledge should only be
required for more complex applications, and even then it should only be the
high level structure in question, and not the details of how those structures
are represented. Since MIME content types are used widely in modern internet
software (not just email), this will be a familiar concept to many programmers.
The following sections describe the functionality of the :mod:`email` package.
We start with the :mod:`~email.message` object model, which is the primary
interface an application will use, and follow that with the
:mod:`~email.parser` and :mod:`~email.generator` components. Then we cover the
:mod:`~email.policy` controls, which completes the treatment of the main
components of the library.
The next three sections cover the exceptions the package may raise and the
defects (non-compliance with the RFCs) that the :mod:`~email.parser` may
detect. Then we cover the :mod:`~email.headerregistry` and the
:mod:`~email.contentmanager` sub-components, which provide tools for doing more
detailed manipulation of headers and payloads, respectively. Both of these
components contain features relevant to consuming and producing non-trivial
messages, but also document their extensibility APIs, which will be of interest
to advanced applications.
Following those is a set of examples of using the fundamental parts of the APIs
covered in the preceding sections.
The foregoing represent the modern (unicode friendly) API of the email package.
The remaining sections, starting with the :class:`~email.message.Message`
class, cover the legacy :data:`~email.policy.compat32` API that deals much more
directly with the details of how email messages are represented. The
:data:`~email.policy.compat32` API does *not* hide the details of the RFCs from
the application, but for applications that need to operate at that level, they
can be useful tools. This documentation is also relevant for applications that
are still using the :mod:`~email.policy.compat32` API for backward
compatibility reasons.
.. versionchanged:: 3.6
Docs reorganized and rewritten to promote the new
:class:`~email.message.EmailMessage`/:class:`~email.policy.EmailPolicy`
API.
Contents of the :mod:`email` package documentation:
.. toctree::
email.message.rst
email.parser.rst
email.generator.rst
email.policy.rst
email.errors.rst
email.headerregistry.rst
email.contentmanager.rst
email.examples.rst
Legacy API:
.. toctree::
email.compat32-message.rst
email.mime.rst
email.header.rst
email.charset.rst
email.encoders.rst
email.utils.rst
email.iterators.rst
.. seealso::
Module :mod:`smtplib`
SMTP (Simple Mail Transport Protocol) client
Module :mod:`poplib`
POP (Post Office Protocol) client
Module :mod:`imaplib`
IMAP (Internet Message Access Protocol) client
Module :mod:`nntplib`
NNTP (Net News Transport Protocol) client
Module :mod:`mailbox`
Tools for creating, reading, and managing collections of messages on disk
using a variety standard formats.
Module :mod:`smtpd`
SMTP server framework (primarily useful for testing)

229
web/python-docs/_sources/library/email.utils.rst.txt Normal file
View File

@@ -0,0 +1,229 @@
:mod:`email.utils`: Miscellaneous utilities
-------------------------------------------
.. module:: email.utils
:synopsis: Miscellaneous email package utilities.
**Source code:** :source:`Lib/email/utils.py`
--------------
There are a couple of useful utilities provided in the :mod:`email.utils`
module:
.. function:: localtime(dt=None)
Return local time as an aware datetime object. If called without
arguments, return current time. Otherwise *dt* argument should be a
:class:`~datetime.datetime` instance, and it is converted to the local time
zone according to the system time zone database. If *dt* is naive (that
is, ``dt.tzinfo`` is ``None``), it is assumed to be in local time. In this
case, a positive or zero value for *isdst* causes ``localtime`` to presume
initially that summer time (for example, Daylight Saving Time) is or is not
(respectively) in effect for the specified time. A negative value for
*isdst* causes the ``localtime`` to attempt to divine whether summer time
is in effect for the specified time.
.. versionadded:: 3.3
.. function:: make_msgid(idstring=None, domain=None)
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. Optional *domain* if
given provides the portion of the msgid after the '@'. The default is the
local hostname. It is not normally necessary to override this default, but
may be useful certain cases, such as a constructing distributed system that
uses a consistent domain name across multiple hosts.
.. versionchanged:: 3.2
Added the *domain* keyword.
The remaining functions are part of the legacy (``Compat32``) email API. There
is no need to directly use these with the new API, since the parsing and
formatting they provide is done automatically by the header parsing machinery
of the new API.
.. 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, *, strict=True)
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.
If *strict* is true, use a strict parser which rejects malformed inputs.
.. versionchanged:: 3.8.20
Add *strict* optional parameter and reject malformed inputs by default.
.. function:: formataddr(pair, charset='utf-8')
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.
Optional *charset* is the character set that will be used in the :rfc:`2047`
encoding of the ``realname`` if the ``realname`` contains non-ASCII
characters. Can be an instance of :class:`str` or a
:class:`~email.charset.Charset`. Defaults to ``utf-8``.
.. versionchanged:: 3.3
Added the *charset* option.
.. function:: getaddresses(fieldvalues, *, strict=True)
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>`.
If *strict* is true, use a strict parser which rejects malformed inputs.
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)
.. versionchanged:: 3.8.20
Add *strict* optional parameter and reject malformed inputs by default.
.. 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 ``0``, which represents
UTC. Note that indexes 6, 7, and 8 of the result tuple are not usable.
.. function:: parsedate_to_datetime(date)
The inverse of :func:`format_datetime`. Performs the same function as
:func:`parsedate`, but on success returns a :mod:`~datetime.datetime`. If
the input date has a timezone of ``-0000``, the ``datetime`` will be a naive
``datetime``, and if the date is conforming to the RFCs it will represent a
time in UTC but with no indication of the actual source timezone of the
message the date comes from. If the input date has any other valid timezone
offset, the ``datetime`` will be an aware ``datetime`` with the
corresponding a :class:`~datetime.timezone` :class:`~datetime.tzinfo`.
.. versionadded:: 3.3
.. 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=None, localtime=False, usegmt=False)
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``.
.. function:: format_datetime(dt, usegmt=False)
Like ``formatdate``, but the input is a :mod:`datetime` instance. If it is
a naive datetime, it is assumed to be "UTC with no information about the
source timezone", and the conventional ``-0000`` is used for the timezone.
If it is an aware ``datetime``, then the numeric timezone offset is used.
If it is an aware timezone with offset zero, then *usegmt* may be set to
``True``, in which case the string ``GMT`` is used instead of the numeric
timezone offset. This provides a way to generate standards conformant HTTP
date headers.
.. versionadded:: 3.3
.. function:: decode_rfc2231(s)
Decode the string *s* according to :rfc:`2231`.
.. function:: encode_rfc2231(s, charset=None, language=None)
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='replace', fallback_charset='us-ascii')
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 :class:`str`'s
:func:`~str.encode` method; 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)``.
.. 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`.

135
web/python-docs/_sources/library/ensurepip.rst.txt Normal file
View File

@@ -0,0 +1,135 @@
:mod:`ensurepip` --- Bootstrapping the ``pip`` installer
========================================================
.. module:: ensurepip
:synopsis: Bootstrapping the "pip" installer into an existing Python
installation or virtual environment.
.. versionadded:: 3.4
--------------
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.
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 ``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 ``pipX``
script will *not* be installed.
* ``--default-pip``: if a "default pip" installation is requested, the
``pip`` script will be installed in addition to the two regular scripts.
Providing both of the script selection options will trigger an exception.
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=False, \
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 ``pipX`` and ``pipX.Y`` will be installed (where
X.Y stands for the current version of Python).
If *altinstall* is set, then ``pipX`` will *not* be installed.
If *default_pip* is set, then ``pip`` will be installed in addition to
the two regular scripts.
Setting both *altinstall* and *default_pip* will trigger
:exc:`ValueError`.
*verbosity* controls the level of output to :data:`sys.stdout` from the
bootstrapping operation.
.. audit-event:: ensurepip.bootstrap root ensurepip.bootstrap
.. 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``).

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