mirror of
https://github.com/python/cpython.git
synced 2024-11-24 17:47:13 +01:00
Merged revisions 80605-80609,80642-80646,80651-80652,80674,80684-80686,80748,80852,80854,80870,80872-80873,80907,80915-80916,80951-80952,80976-80977,80985,81038-81040,81042,81053,81070,81104-81105,81114,81125,81245,81285,81402,81463,81516,81562-81563,81567,81593,81635,81680-81681,81684,81801,81888,81931-81933,81939-81942,81963,81984,81991,82120,82188,82264-82267 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r80605 | andrew.kuchling | 2010-04-28 19:22:16 -0500 (Wed, 28 Apr 2010) | 1 line
Add various items
........
r80606 | andrew.kuchling | 2010-04-28 20:44:30 -0500 (Wed, 28 Apr 2010) | 6 lines
Fix doubled 'the'.
Markup fixes to use :exc:, :option: in a few places.
(Glitch: unittest.main's -c ends up a link to the Python
interpreter's -c option. Should we skip using :option: for that
switch, or disable the auto-linking somehow?)
........
r80607 | andrew.kuchling | 2010-04-28 20:45:41 -0500 (Wed, 28 Apr 2010) | 1 line
Add various unittest items
........
r80608 | benjamin.peterson | 2010-04-28 22:18:05 -0500 (Wed, 28 Apr 2010) | 1 line
update pypy description
........
r80609 | benjamin.peterson | 2010-04-28 22:30:59 -0500 (Wed, 28 Apr 2010) | 1 line
update pypy url
........
r80642 | andrew.kuchling | 2010-04-29 19:49:09 -0500 (Thu, 29 Apr 2010) | 1 line
Always add space after RFC; reword paragraph
........
r80643 | andrew.kuchling | 2010-04-29 19:52:31 -0500 (Thu, 29 Apr 2010) | 6 lines
Reword paragraph to make its meaning clearer.
Antoine Pitrou: is my version of the paragraph still correct?
R. David Murray: is this more understandable than the previous version?
........
r80644 | andrew.kuchling | 2010-04-29 20:02:15 -0500 (Thu, 29 Apr 2010) | 1 line
Fix typos
........
r80645 | andrew.kuchling | 2010-04-29 20:32:47 -0500 (Thu, 29 Apr 2010) | 1 line
Markup fix; clarify by adding 'in that order'
........
r80646 | andrew.kuchling | 2010-04-29 20:33:40 -0500 (Thu, 29 Apr 2010) | 1 line
Add various items; rearrange unittest section a bit
........
r80651 | andrew.kuchling | 2010-04-30 08:46:55 -0500 (Fri, 30 Apr 2010) | 1 line
Minor grammar re-wording
........
r80652 | andrew.kuchling | 2010-04-30 08:47:34 -0500 (Fri, 30 Apr 2010) | 1 line
Add item
........
r80674 | andrew.kuchling | 2010-04-30 20:19:16 -0500 (Fri, 30 Apr 2010) | 1 line
Add various items
........
r80684 | andrew.kuchling | 2010-05-01 07:05:52 -0500 (Sat, 01 May 2010) | 1 line
Minor grammar fix
........
r80685 | andrew.kuchling | 2010-05-01 07:06:51 -0500 (Sat, 01 May 2010) | 1 line
Describe memoryview
........
r80686 | antoine.pitrou | 2010-05-01 07:16:39 -0500 (Sat, 01 May 2010) | 4 lines
Fix attribution. Travis didn't do much and he did a bad work.
(yes, this is a sensitive subject, sorry)
........
r80748 | andrew.kuchling | 2010-05-03 20:24:22 -0500 (Mon, 03 May 2010) | 1 line
Add some more items; the urlparse change is added twice
........
r80852 | andrew.kuchling | 2010-05-05 20:09:47 -0500 (Wed, 05 May 2010) | 1 line
Reword paragraph; fix filename, which should be pyconfig.h
........
r80854 | andrew.kuchling | 2010-05-05 20:10:56 -0500 (Wed, 05 May 2010) | 1 line
Add various items
........
r80870 | andrew.kuchling | 2010-05-06 09:14:09 -0500 (Thu, 06 May 2010) | 1 line
Describe ElementTree 1.3; rearrange new-module sections; describe dict views as sets; small edits and items
........
r80872 | andrew.kuchling | 2010-05-06 12:21:59 -0500 (Thu, 06 May 2010) | 1 line
Add 2 items; record ideas for two initial sections; clarify wording
........
r80873 | andrew.kuchling | 2010-05-06 12:27:57 -0500 (Thu, 06 May 2010) | 1 line
Change section title; point to unittest2
........
r80907 | andrew.kuchling | 2010-05-06 20:45:14 -0500 (Thu, 06 May 2010) | 1 line
Add a new section on the development plan; add an item
........
r80915 | antoine.pitrou | 2010-05-07 05:15:51 -0500 (Fri, 07 May 2010) | 3 lines
Fix some markup and a class name. Also, wrap a long line.
........
r80916 | andrew.kuchling | 2010-05-07 06:30:47 -0500 (Fri, 07 May 2010) | 1 line
Re-word text
........
r80951 | andrew.kuchling | 2010-05-07 20:15:26 -0500 (Fri, 07 May 2010) | 1 line
Add two items
........
r80952 | andrew.kuchling | 2010-05-07 20:35:55 -0500 (Fri, 07 May 2010) | 1 line
Get accents correct
........
r80976 | andrew.kuchling | 2010-05-08 08:28:03 -0500 (Sat, 08 May 2010) | 1 line
Add logging.dictConfig example; give up on writing a Ttk example
........
r80977 | andrew.kuchling | 2010-05-08 08:29:46 -0500 (Sat, 08 May 2010) | 1 line
Markup fixes
........
r80985 | andrew.kuchling | 2010-05-08 10:39:46 -0500 (Sat, 08 May 2010) | 7 lines
Write summary of the 2.7 release; rewrite the future section some more;
mention PYTHONWARNINGS env. var; tweak some examples for readability.
And with this commit, the "What's New" is done... except for a
complete read-through to polish the text, and fixing any reported errors,
but those tasks can easily wait until after beta2.
........
r81038 | benjamin.peterson | 2010-05-09 16:09:40 -0500 (Sun, 09 May 2010) | 1 line
finish clause
........
r81039 | andrew.kuchling | 2010-05-10 09:18:27 -0500 (Mon, 10 May 2010) | 1 line
Markup fix; re-word a sentence
........
r81040 | andrew.kuchling | 2010-05-10 09:20:12 -0500 (Mon, 10 May 2010) | 1 line
Use title case
........
r81042 | andrew.kuchling | 2010-05-10 10:03:35 -0500 (Mon, 10 May 2010) | 1 line
Link to unittest2 article
........
r81053 | florent.xicluna | 2010-05-10 14:59:22 -0500 (Mon, 10 May 2010) | 2 lines
Add a link on maketrans().
........
r81070 | andrew.kuchling | 2010-05-10 18:13:41 -0500 (Mon, 10 May 2010) | 1 line
Fix typo
........
r81104 | andrew.kuchling | 2010-05-11 19:38:44 -0500 (Tue, 11 May 2010) | 1 line
Revision pass: lots of edits, typo fixes, rearrangements
........
r81105 | andrew.kuchling | 2010-05-11 19:40:47 -0500 (Tue, 11 May 2010) | 1 line
Let's call this done
........
r81114 | andrew.kuchling | 2010-05-12 08:56:07 -0500 (Wed, 12 May 2010) | 1 line
Grammar fix
........
r81125 | andrew.kuchling | 2010-05-12 13:56:48 -0500 (Wed, 12 May 2010) | 1 line
#8696: add documentation for logging.config.dictConfig (PEP 391)
........
r81245 | andrew.kuchling | 2010-05-16 18:31:16 -0500 (Sun, 16 May 2010) | 1 line
Add cross-reference to later section
........
r81285 | vinay.sajip | 2010-05-18 03:16:27 -0500 (Tue, 18 May 2010) | 1 line
Fixed minor typo in ReST markup.
........
r81402 | vinay.sajip | 2010-05-21 12:41:34 -0500 (Fri, 21 May 2010) | 1 line
Updated logging documentation with more dictConfig information.
........
r81463 | georg.brandl | 2010-05-22 03:17:23 -0500 (Sat, 22 May 2010) | 1 line
#8785: less confusing description of regex.find*.
........
r81516 | andrew.kuchling | 2010-05-25 08:34:08 -0500 (Tue, 25 May 2010) | 1 line
Add three items
........
r81562 | andrew.kuchling | 2010-05-27 08:22:53 -0500 (Thu, 27 May 2010) | 1 line
Rewrite wxWidgets section
........
r81563 | andrew.kuchling | 2010-05-27 08:30:09 -0500 (Thu, 27 May 2010) | 1 line
Remove top-level 'General Questions' section, pushing up the questions it contains
........
r81567 | andrew.kuchling | 2010-05-27 16:29:59 -0500 (Thu, 27 May 2010) | 1 line
Add item
........
r81593 | georg.brandl | 2010-05-29 03:46:18 -0500 (Sat, 29 May 2010) | 1 line
#8616: add new turtle demo "nim".
........
r81635 | georg.brandl | 2010-06-01 02:25:23 -0500 (Tue, 01 Jun 2010) | 1 line
Put docs for RegexObject.search() before RegexObject.match() to mirror re.search() and re.match() order.
........
r81680 | vinay.sajip | 2010-06-03 17:34:42 -0500 (Thu, 03 Jun 2010) | 1 line
Issue #8890: Documentation changed to avoid reference to temporary files.
........
r81681 | sean.reifschneider | 2010-06-03 20:51:26 -0500 (Thu, 03 Jun 2010) | 2 lines
Issue8810: Clearing up docstring for tzinfo.utcoffset.
........
r81684 | vinay.sajip | 2010-06-04 08:41:02 -0500 (Fri, 04 Jun 2010) | 1 line
Issue #8890: Documentation changed to avoid reference to temporary files - other cases covered.
........
r81801 | andrew.kuchling | 2010-06-07 08:38:40 -0500 (Mon, 07 Jun 2010) | 1 line
#8875: Remove duplicated paragraph
........
r81888 | andrew.kuchling | 2010-06-10 20:54:58 -0500 (Thu, 10 Jun 2010) | 1 line
Add a few more items
........
r81931 | georg.brandl | 2010-06-12 01:26:54 -0500 (Sat, 12 Jun 2010) | 1 line
Fix punctuation.
........
r81932 | georg.brandl | 2010-06-12 01:28:58 -0500 (Sat, 12 Jun 2010) | 1 line
Document that an existing directory raises in mkdir().
........
r81933 | georg.brandl | 2010-06-12 01:45:33 -0500 (Sat, 12 Jun 2010) | 1 line
Update version in README.
........
r81939 | georg.brandl | 2010-06-12 04:45:01 -0500 (Sat, 12 Jun 2010) | 1 line
Use newer toctree syntax.
........
r81940 | georg.brandl | 2010-06-12 04:45:28 -0500 (Sat, 12 Jun 2010) | 1 line
Add document on how to build.
........
r81941 | georg.brandl | 2010-06-12 04:45:58 -0500 (Sat, 12 Jun 2010) | 1 line
Fix gratuitous indentation.
........
r81942 | georg.brandl | 2010-06-12 04:46:03 -0500 (Sat, 12 Jun 2010) | 1 line
Update README.
........
r81963 | andrew.kuchling | 2010-06-12 15:00:55 -0500 (Sat, 12 Jun 2010) | 1 line
Grammar fix
........
r81984 | georg.brandl | 2010-06-14 10:58:39 -0500 (Mon, 14 Jun 2010) | 1 line
#8993: fix reference.
........
r81991 | andrew.kuchling | 2010-06-14 19:38:58 -0500 (Mon, 14 Jun 2010) | 1 line
Add another bunch of items
........
r82120 | andrew.kuchling | 2010-06-20 16:45:45 -0500 (Sun, 20 Jun 2010) | 1 line
Note that Python 3.x isn't covered; add forward ref. for UTF-8; note error in 2.5 and up
........
r82188 | benjamin.peterson | 2010-06-23 19:02:46 -0500 (Wed, 23 Jun 2010) | 1 line
remove reverted changed
........
r82264 | georg.brandl | 2010-06-27 05:47:47 -0500 (Sun, 27 Jun 2010) | 1 line
Confusing punctuation.
........
r82265 | georg.brandl | 2010-06-27 05:49:23 -0500 (Sun, 27 Jun 2010) | 1 line
Use designated syntax for optional grammar element.
........
r82266 | georg.brandl | 2010-06-27 05:51:44 -0500 (Sun, 27 Jun 2010) | 1 line
Fix URL.
........
r82267 | georg.brandl | 2010-06-27 05:55:38 -0500 (Sun, 27 Jun 2010) | 1 line
Two typos.
........
This commit is contained in:
Benjamin Peterson
parent
30b7a90033
commit
d7c3ed54ef
@ -14,12 +14,11 @@ those familiar with the previous docs written in LaTeX.
|
||||
Building the docs
|
||||
=================
|
||||
|
||||
You need to install Python 2.4 or higher (but Python 3.0 is not supported yet);
|
||||
the toolset used to build the docs are written in Python. The toolset used
|
||||
to build the documentation is called *Sphinx*, it is not included in this
|
||||
tree, but maintained separately in the Python Subversion repository. Also
|
||||
needed are Jinja, a templating engine (included in Sphinx as a Subversion
|
||||
external), and optionally Pygments, a code highlighter.
|
||||
You need to have Python 2.4 or higher installed; the toolset used to build the
|
||||
docs is written in Python. It is called *Sphinx*, it is not included in this
|
||||
tree, but maintained separately. Also needed are the docutils, supplying the
|
||||
base markup that Sphinx uses, Jinja, a templating engine, and optionally
|
||||
Pygments, a code highlighter.
|
||||
|
||||
|
||||
Using make
|
||||
@ -47,29 +46,29 @@ Available make targets are:
|
||||
convert them into a single Compiled HTML (.chm) file -- these are popular
|
||||
under Microsoft Windows, but very handy on every platform.
|
||||
|
||||
To create the CHM file, you need to run the Microsoft HTML Help Workshop
|
||||
over the generated project (.hhp) file.
|
||||
To create the CHM file, you need to run the Microsoft HTML Help Workshop over
|
||||
the generated project (.hhp) file.
|
||||
|
||||
* "latex", which builds LaTeX source files that can be run with "pdflatex"
|
||||
to produce PDF documents.
|
||||
* "latex", which builds LaTeX source files as input to "pdflatex" to produce
|
||||
PDF documents.
|
||||
|
||||
* "text", which builds a plain text file for each source file.
|
||||
|
||||
* "linkcheck", which checks all external references to see whether they are
|
||||
broken, redirected or malformed, and outputs this information to stdout
|
||||
as well as a plain-text (.txt) file.
|
||||
broken, redirected or malformed, and outputs this information to stdout as
|
||||
well as a plain-text (.txt) file.
|
||||
|
||||
* "changes", which builds an overview over all versionadded/versionchanged/
|
||||
deprecated items in the current version. This is meant as a help for the
|
||||
writer of the "What's New" document.
|
||||
|
||||
* "coverage", which builds a coverage overview for standard library modules
|
||||
and C API.
|
||||
* "coverage", which builds a coverage overview for standard library modules and
|
||||
C API.
|
||||
|
||||
* "pydoc-topics", which builds a Python module containing a dictionary
|
||||
with plain text documentation for the labels defined in
|
||||
`tools/sphinxext/pyspecific.py` -- pydoc needs these to show topic
|
||||
and keyword help.
|
||||
* "pydoc-topics", which builds a Python module containing a dictionary with
|
||||
plain text documentation for the labels defined in
|
||||
`tools/sphinxext/pyspecific.py` -- pydoc needs these to show topic and
|
||||
keyword help.
|
||||
|
||||
A "make update" updates the Subversion checkouts in `tools/`.
|
||||
|
||||
@ -95,7 +94,7 @@ You also need Jinja2, either by checking it out via ::
|
||||
|
||||
or by installing it from PyPI.
|
||||
|
||||
You can optionally also install Pygments, either as a checkout via ::
|
||||
You can optionally also install Pygments, either as a checkout via ::
|
||||
|
||||
svn co http://svn.python.org/projects/external/Pygments-1.3.1/pygments tools/pygments
|
||||
|
||||
|
||||
@ -385,7 +385,7 @@ Initialization, Finalization, and Threads
|
||||
|
||||
.. cfunction:: void PySys_SetArgv(int argc, wchar_t **argv)
|
||||
|
||||
This function works like :cfunc:`PySys_SetArgv` with *updatepath* set to 1.
|
||||
This function works like :cfunc:`PySys_SetArgvEx` with *updatepath* set to 1.
|
||||
|
||||
|
||||
.. cfunction:: void Py_SetPythonHome(wchar_t *home)
|
||||
|
||||
@ -322,7 +322,7 @@ the :option:`--no-target-compile` and/or the :option:`--no-target-optimize`
|
||||
option.
|
||||
|
||||
By default the installer will display the cool "Python Powered" logo when it is
|
||||
run, but you can also supply your own 152x161 bitmap which must be a Windows
|
||||
run, but you can also supply your own 152x261 bitmap which must be a Windows
|
||||
:file:`.bmp` file with the :option:`--bitmap` option.
|
||||
|
||||
The installer will also display a large title on the desktop background window
|
||||
@ -375,7 +375,7 @@ check or modify your existing install.)
|
||||
The Postinstallation script
|
||||
---------------------------
|
||||
|
||||
Starting with Python 2.3, a postinstallation script can be specified which the
|
||||
Starting with Python 2.3, a postinstallation script can be specified with the
|
||||
:option:`--install-script` option. The basename of the script must be
|
||||
specified, and the script filename must also be listed in the scripts argument
|
||||
to the setup function.
|
||||
|
||||
91
Doc/documenting/building.rst
Normal file
91
Doc/documenting/building.rst
Normal file
@ -0,0 +1,91 @@
|
||||
Building the documentation
|
||||
==========================
|
||||
|
||||
You need to have Python 2.4 or higher installed; the toolset used to build the
|
||||
docs is written in Python. It is called *Sphinx*, it is not included in this
|
||||
tree, but maintained separately. Also needed are the docutils, supplying the
|
||||
base markup that Sphinx uses, Jinja, a templating engine, and optionally
|
||||
Pygments, a code highlighter.
|
||||
|
||||
|
||||
Using make
|
||||
----------
|
||||
|
||||
Luckily, a Makefile has been prepared so that on Unix, provided you have
|
||||
installed Python and Subversion, you can just run ::
|
||||
|
||||
make html
|
||||
|
||||
to check out the necessary toolset in the `tools/` subdirectory and build the
|
||||
HTML output files. To view the generated HTML, point your favorite browser at
|
||||
the top-level index `build/html/index.html` after running "make".
|
||||
|
||||
Available make targets are:
|
||||
|
||||
* "html", which builds standalone HTML files for offline viewing.
|
||||
|
||||
* "htmlhelp", which builds HTML files and a HTML Help project file usable to
|
||||
convert them into a single Compiled HTML (.chm) file -- these are popular
|
||||
under Microsoft Windows, but very handy on every platform.
|
||||
|
||||
To create the CHM file, you need to run the Microsoft HTML Help Workshop
|
||||
over the generated project (.hhp) file.
|
||||
|
||||
* "latex", which builds LaTeX source files as input to "pdflatex" to produce
|
||||
PDF documents.
|
||||
|
||||
* "text", which builds a plain text file for each source file.
|
||||
|
||||
* "linkcheck", which checks all external references to see whether they are
|
||||
broken, redirected or malformed, and outputs this information to stdout
|
||||
as well as a plain-text (.txt) file.
|
||||
|
||||
* "changes", which builds an overview over all versionadded/versionchanged/
|
||||
deprecated items in the current version. This is meant as a help for the
|
||||
writer of the "What's New" document.
|
||||
|
||||
* "coverage", which builds a coverage overview for standard library modules
|
||||
and C API.
|
||||
|
||||
* "pydoc-topics", which builds a Python module containing a dictionary with
|
||||
plain text documentation for the labels defined in
|
||||
`tools/sphinxext/pyspecific.py` -- pydoc needs these to show topic and
|
||||
keyword help.
|
||||
|
||||
A "make update" updates the Subversion checkouts in `tools/`.
|
||||
|
||||
|
||||
Without make
|
||||
------------
|
||||
|
||||
You'll need to install the Sphinx package, either by checking it out via ::
|
||||
|
||||
svn co http://svn.python.org/projects/external/Sphinx-0.6.5/sphinx tools/sphinx
|
||||
|
||||
or by installing it from PyPI.
|
||||
|
||||
Then, you need to install Docutils, either by checking it out via ::
|
||||
|
||||
svn co http://svn.python.org/projects/external/docutils-0.6/docutils tools/docutils
|
||||
|
||||
or by installing it from http://docutils.sf.net/.
|
||||
|
||||
You also need Jinja2, either by checking it out via ::
|
||||
|
||||
svn co http://svn.python.org/projects/external/Jinja-2.3.1/jinja2 tools/jinja2
|
||||
|
||||
or by installing it from PyPI.
|
||||
|
||||
You can optionally also install Pygments, either as a checkout via ::
|
||||
|
||||
svn co http://svn.python.org/projects/external/Pygments-1.3.1/pygments tools/pygments
|
||||
|
||||
or from PyPI at http://pypi.python.org/pypi/Pygments.
|
||||
|
||||
|
||||
Then, make an output directory, e.g. under `build/`, and run ::
|
||||
|
||||
python tools/sphinx-build.py -b<builder> . build/<outputdirectory>
|
||||
|
||||
where `<builder>` is one of html, text, latex, or htmlhelp (for explanations see
|
||||
the make targets above).
|
||||
@ -10,9 +10,9 @@ contributed by various authors. The markup used for the Python documentation is
|
||||
`reStructuredText`_, developed by the `docutils`_ project, amended by custom
|
||||
directives and using a toolset named `Sphinx`_ to postprocess the HTML output.
|
||||
|
||||
This document describes the style guide for our documentation, the custom
|
||||
reStructuredText markup introduced to support Python documentation and how it
|
||||
should be used, as well as the Sphinx build system.
|
||||
This document describes the style guide for our documentation as well as the
|
||||
custom reStructuredText markup introduced by Sphinx to support Python
|
||||
documentation and how it should be used.
|
||||
|
||||
.. _reStructuredText: http://docutils.sf.net/rst.html
|
||||
.. _docutils: http://docutils.sf.net/
|
||||
@ -35,3 +35,4 @@ should be used, as well as the Sphinx build system.
|
||||
rest.rst
|
||||
markup.rst
|
||||
fromlatex.rst
|
||||
building.rst
|
||||
|
||||
@ -698,10 +698,10 @@ tables of contents. The ``toctree`` directive is the central element.
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
intro.rst
|
||||
strings.rst
|
||||
datatypes.rst
|
||||
numeric.rst
|
||||
intro
|
||||
strings
|
||||
datatypes
|
||||
numeric
|
||||
(many more files listed here)
|
||||
|
||||
This accomplishes two things:
|
||||
@ -709,8 +709,8 @@ tables of contents. The ``toctree`` directive is the central element.
|
||||
* Tables of contents from all those files are inserted, with a maximum depth
|
||||
of two, that means one nested heading. ``toctree`` directives in those
|
||||
files are also taken into account.
|
||||
* Sphinx knows that the relative order of the files ``intro.rst``,
|
||||
``strings.rst`` and so forth, and it knows that they are children of the
|
||||
* Sphinx knows that the relative order of the files ``intro``,
|
||||
``strings`` and so forth, and it knows that they are children of the
|
||||
shown file, the library index. From this information it generates "next
|
||||
chapter", "previous chapter" and "parent chapter" links.
|
||||
|
||||
|
||||
@ -7,7 +7,7 @@ The Python documentation should follow the `Apple Publications Style Guide`_
|
||||
wherever possible. This particular style guide was selected mostly because it
|
||||
seems reasonable and is easy to get online.
|
||||
|
||||
Topics which are not covered in the Apple's style guide will be discussed in
|
||||
Topics which are not covered in Apple's style guide will be discussed in
|
||||
this document.
|
||||
|
||||
All reST files use an indentation of 3 spaces. The maximum line length is 80
|
||||
|
||||
@ -13,14 +13,14 @@ General GUI Questions
|
||||
=====================
|
||||
|
||||
What platform-independent GUI toolkits exist for Python?
|
||||
--------------------------------------------------------
|
||||
========================================================
|
||||
|
||||
Depending on what platform(s) you are aiming at, there are several.
|
||||
|
||||
.. XXX check links
|
||||
|
||||
Tkinter
|
||||
'''''''
|
||||
-------
|
||||
|
||||
Standard builds of Python include an object-oriented interface to the Tcl/Tk
|
||||
widget set, called Tkinter. This is probably the easiest to install and use.
|
||||
@ -29,22 +29,27 @@ page at http://www.tcl.tk. Tcl/Tk is fully portable to the MacOS, Windows, and
|
||||
Unix platforms.
|
||||
|
||||
wxWidgets
|
||||
'''''''''
|
||||
---------
|
||||
|
||||
wxWidgets is a GUI class library written in C++ that's a portable
|
||||
interface to various platform-specific libraries, and that has a
|
||||
Python interface called `wxPython <http://www.wxpython.org>`__.
|
||||
wxWidgets (http://www.wxwidgets.org) is a free, portable GUI class
|
||||
library written in C++ that provides a native look and feel on a
|
||||
number of platforms, with Windows, MacOS X, GTK, X11, all listed as
|
||||
current stable targets. Language bindings are available for a number
|
||||
of languages including Python, Perl, Ruby, etc.
|
||||
|
||||
wxWidgets preserves the look and feel of the
|
||||
underlying graphics toolkit, and has a large set of widgets and
|
||||
collection of GDI classes. See `the wxWidgets page
|
||||
<http://www.wxwidgets.org>`_ for more details.
|
||||
wxPython (http://www.wxpython.org) is the Python binding for
|
||||
wxwidgets. While it often lags slightly behind the official wxWidgets
|
||||
releases, it also offers a number of features via pure Python
|
||||
extensions that are not available in other language bindings. There
|
||||
is an active wxPython user and developer community.
|
||||
|
||||
Both wxWidgets and wxPython are free, open source, software with
|
||||
permissive licences that allow their use in commercial products as
|
||||
well as in freeware or shareware.
|
||||
|
||||
wxWidgets supports Windows and MacOS; on Unix variants,
|
||||
it supports both GTk+ and Motif toolkits.
|
||||
|
||||
Qt
|
||||
'''
|
||||
---
|
||||
|
||||
There are bindings available for the Qt toolkit (`PyQt
|
||||
<http://www.riverbankcomputing.co.uk/software/pyqt/>`_) and for KDE (`PyKDE <http://www.riverbankcomputing.co.uk/software/pykde/intro>`__). If
|
||||
@ -55,13 +60,13 @@ Qt 4.5 upwards is licensed under the LGPL license) a Qt license from `Trolltech
|
||||
<http://www.trolltech.com>`_.
|
||||
|
||||
Gtk+
|
||||
''''
|
||||
----
|
||||
|
||||
PyGtk bindings for the `Gtk+ toolkit <http://www.gtk.org>`_ have been
|
||||
implemented by James Henstridge; see <http://www.pygtk.org>.
|
||||
|
||||
FLTK
|
||||
''''
|
||||
----
|
||||
|
||||
Python bindings for `the FLTK toolkit <http://www.fltk.org>`_, a simple yet
|
||||
powerful and mature cross-platform windowing system, are available from `the
|
||||
@ -69,7 +74,7 @@ PyFLTK project <http://pyfltk.sourceforge.net>`_.
|
||||
|
||||
|
||||
FOX
|
||||
'''
|
||||
----
|
||||
|
||||
A wrapper for `the FOX toolkit <http://www.fox-toolkit.org/>`_ called `FXpy
|
||||
<http://fxpy.sourceforge.net/>`_ is available. FOX supports both Unix variants
|
||||
@ -77,13 +82,13 @@ and Windows.
|
||||
|
||||
|
||||
OpenGL
|
||||
''''''
|
||||
------
|
||||
|
||||
For OpenGL bindings, see `PyOpenGL <http://pyopengl.sourceforge.net>`_.
|
||||
|
||||
|
||||
What platform-specific GUI toolkits exist for Python?
|
||||
-----------------------------------------------------
|
||||
========================================================
|
||||
|
||||
`The Mac port <http://python.org/download/mac>`_ by Jack Jansen has a rich and
|
||||
ever-growing set of modules that support the native Mac toolbox calls. The port
|
||||
|
||||
@ -5,9 +5,6 @@
|
||||
:Author: A. M. Kuchling
|
||||
:Release: 0.31
|
||||
|
||||
(This is a first draft. Please send comments/error reports/suggestions to
|
||||
amk@amk.ca.)
|
||||
|
||||
In this document, we'll take a tour of Python's features suitable for
|
||||
implementing programs in a functional style. After an introduction to the
|
||||
concepts of functional programming, we'll look at language features such as
|
||||
|
||||
@ -4,10 +4,12 @@
|
||||
Unicode HOWTO
|
||||
*****************
|
||||
|
||||
:Release: 1.1
|
||||
:Release: 1.11
|
||||
|
||||
This HOWTO discusses Python's support for Unicode, and explains various problems
|
||||
that people commonly encounter when trying to work with Unicode.
|
||||
This HOWTO discusses Python 2.x's support for Unicode, and explains
|
||||
various problems that people commonly encounter when trying to work
|
||||
with Unicode. (This HOWTO has not yet been updated to cover the 3.x
|
||||
versions of Python.)
|
||||
|
||||
|
||||
Introduction to Unicode
|
||||
@ -146,8 +148,9 @@ problems.
|
||||
4. Many Internet standards are defined in terms of textual data, and can't
|
||||
handle content with embedded zero bytes.
|
||||
|
||||
Generally people don't use this encoding, instead choosing other encodings that
|
||||
are more efficient and convenient.
|
||||
Generally people don't use this encoding, instead choosing other
|
||||
encodings that are more efficient and convenient. UTF-8 is probably
|
||||
the most commonly supported encoding; it will be discussed below.
|
||||
|
||||
Encodings don't have to handle every possible Unicode character, and most
|
||||
encodings don't. The rules for converting a Unicode string into the ASCII
|
||||
@ -223,8 +226,8 @@ Wikipedia entries are often helpful; see the entries for "character encoding"
|
||||
<http://en.wikipedia.org/wiki/UTF-8>, for example.
|
||||
|
||||
|
||||
Python's Unicode Support
|
||||
========================
|
||||
Python 2.x's Unicode Support
|
||||
============================
|
||||
|
||||
Now that you've learned the rudiments of Unicode, we can look at Python's
|
||||
Unicode features.
|
||||
@ -266,8 +269,8 @@ Unicode result). The following examples show the differences::
|
||||
>>> b'\x80abc'.decode("utf-8", "ignore")
|
||||
'abc'
|
||||
|
||||
Encodings are specified as strings containing the encoding's name. Python comes
|
||||
with roughly 100 different encodings; see the Python Library Reference at
|
||||
Encodings are specified as strings containing the encoding's name. Python 3.2
|
||||
comes with roughly 100 different encodings; see the Python Library Reference at
|
||||
:ref:`standard-encodings` for a list. Some encodings have multiple names; for
|
||||
example, 'latin-1', 'iso_8859_1' and '8859' are all synonyms for the same
|
||||
encoding.
|
||||
@ -626,7 +629,10 @@ Version 1.02: posted August 16 2005. Corrects factual errors.
|
||||
|
||||
Version 1.1: Feb-Nov 2008. Updates the document with respect to Python 3 changes.
|
||||
|
||||
Version 1.11: posted June 20 2010. Notes that Python 3.x is not covered,
|
||||
and that the HOWTO only covers 2.x.
|
||||
|
||||
.. comment Describe Python 3.x support (new section? new document?)
|
||||
.. comment Additional topic: building Python w/ UCS2 or UCS4 support
|
||||
.. comment Describe use of codecs.StreamRecoder and StreamReaderWriter
|
||||
|
||||
|
||||
@ -15,7 +15,7 @@ the week to Sunday (6) or to any other weekday. Parameters that specify dates
|
||||
are given as integers. For related
|
||||
functionality, see also the :mod:`datetime` and :mod:`time` modules.
|
||||
|
||||
Most of these functions and classses rely on the :mod:`datetime` module which
|
||||
Most of these functions and classes rely on the :mod:`datetime` module which
|
||||
uses an idealized calendar, the current Gregorian calendar indefinitely extended
|
||||
in both directions. This matches the definition of the "proleptic Gregorian"
|
||||
calendar in Dershowitz and Reingold's book "Calendrical Calculations", where
|
||||
|
||||
@ -53,10 +53,12 @@ Simple examples
|
||||
|
||||
Most applications are probably going to want to log to a file, so let's start
|
||||
with that case. Using the :func:`basicConfig` function, we can set up the
|
||||
default handler so that debug messages are written to a file::
|
||||
default handler so that debug messages are written to a file (in the example,
|
||||
we assume that you have the appropriate permissions to create a file called
|
||||
*example.log* in the current directory)::
|
||||
|
||||
import logging
|
||||
LOG_FILENAME = '/tmp/logging_example.out'
|
||||
LOG_FILENAME = 'example.log'
|
||||
logging.basicConfig(filename=LOG_FILENAME,level=logging.DEBUG)
|
||||
|
||||
logging.debug('This message should go to the log file')
|
||||
@ -75,7 +77,7 @@ yourself, though, it is simpler to use a :class:`RotatingFileHandler`::
|
||||
import logging
|
||||
import logging.handlers
|
||||
|
||||
LOG_FILENAME = '/tmp/logging_rotatingfile_example.out'
|
||||
LOG_FILENAME = 'logging_rotatingfile_example.out'
|
||||
|
||||
# Set up a specific logger with our desired output level
|
||||
my_logger = logging.getLogger('MyLogger')
|
||||
@ -100,14 +102,14 @@ yourself, though, it is simpler to use a :class:`RotatingFileHandler`::
|
||||
The result should be 6 separate files, each with part of the log history for the
|
||||
application::
|
||||
|
||||
/tmp/logging_rotatingfile_example.out
|
||||
/tmp/logging_rotatingfile_example.out.1
|
||||
/tmp/logging_rotatingfile_example.out.2
|
||||
/tmp/logging_rotatingfile_example.out.3
|
||||
/tmp/logging_rotatingfile_example.out.4
|
||||
/tmp/logging_rotatingfile_example.out.5
|
||||
logging_rotatingfile_example.out
|
||||
logging_rotatingfile_example.out.1
|
||||
logging_rotatingfile_example.out.2
|
||||
logging_rotatingfile_example.out.3
|
||||
logging_rotatingfile_example.out.4
|
||||
logging_rotatingfile_example.out.5
|
||||
|
||||
The most current file is always :file:`/tmp/logging_rotatingfile_example.out`,
|
||||
The most current file is always :file:`logging_rotatingfile_example.out`,
|
||||
and each time it reaches the size limit it is renamed with the suffix
|
||||
``.1``. Each of the existing backup files is renamed to increment the suffix
|
||||
(``.1`` becomes ``.2``, etc.) and the ``.6`` file is erased.
|
||||
@ -321,24 +323,34 @@ order::
|
||||
Configuring Logging
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Programmers can configure logging either by creating loggers, handlers, and
|
||||
formatters explicitly in a main module with the configuration methods listed
|
||||
above (using Python code), or by creating a logging config file. The following
|
||||
code is an example of configuring a very simple logger, a console handler, and a
|
||||
simple formatter in a Python module::
|
||||
Programmers can configure logging in three ways:
|
||||
|
||||
1. Creating loggers, handlers, and formatters explicitly using Python
|
||||
code that calls the configuration methods listed above.
|
||||
2. Creating a logging config file and reading it using the :func:`fileConfig`
|
||||
function.
|
||||
3. Creating a dictionary of configuration information and passing it
|
||||
to the :func:`dictConfig` function.
|
||||
|
||||
The following example configures a very simple logger, a console
|
||||
handler, and a simple formatter using Python code::
|
||||
|
||||
import logging
|
||||
|
||||
# create logger
|
||||
logger = logging.getLogger("simple_example")
|
||||
logger.setLevel(logging.DEBUG)
|
||||
|
||||
# create console handler and set level to debug
|
||||
ch = logging.StreamHandler()
|
||||
ch.setLevel(logging.DEBUG)
|
||||
|
||||
# create formatter
|
||||
formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
|
||||
|
||||
# add formatter to ch
|
||||
ch.setFormatter(formatter)
|
||||
|
||||
# add ch to logger
|
||||
logger.addHandler(ch)
|
||||
|
||||
@ -428,6 +440,45 @@ import mechanisms. Thus, you could use either `handlers.WatchedFileHandler`
|
||||
class defined in package `mypackage` and module `mymodule`, where `mypackage`
|
||||
is available on the Python import path).
|
||||
|
||||
.. versionchanged:: 2.7
|
||||
|
||||
In Python 2.7, a new means of configuring logging has been introduced, using
|
||||
dictionaries to hold configuration information. This provides a superset of the
|
||||
functionality of the config-file-based approach outlined above, and is the
|
||||
recommended configuration method for new applications and deployments. Because
|
||||
a Python dictionary is used to hold configuration information, and since you
|
||||
can populate that dictionary using different means, you have more options for
|
||||
configuration. For example, you can use a configuration file in JSON format,
|
||||
or, if you have access to YAML processing functionality, a file in YAML
|
||||
format, to populate the configuration dictionary. Or, of course, you can
|
||||
construct the dictionary in Python code, receive it in pickled form over a
|
||||
socket, or use whatever approach makes sense for your application.
|
||||
|
||||
Here's an example of the same configuration as above, in YAML format for
|
||||
the new dictionary-based approach::
|
||||
|
||||
version: 1
|
||||
formatters:
|
||||
simple:
|
||||
format: format=%(asctime)s - %(name)s - %(levelname)s - %(message)s
|
||||
handlers:
|
||||
console:
|
||||
class: logging.StreamHandler
|
||||
level: DEBUG
|
||||
formatter: simple
|
||||
stream: ext://sys.stdout
|
||||
loggers:
|
||||
simpleExample:
|
||||
level: DEBUG
|
||||
handlers: [console]
|
||||
propagate: no
|
||||
root:
|
||||
level: DEBUG
|
||||
handlers: [console]
|
||||
|
||||
For more information about logging using a dictionary, see
|
||||
:ref:`logging-config-api`.
|
||||
|
||||
.. _library-config:
|
||||
|
||||
Configuring Logging for a Library
|
||||
@ -1065,14 +1116,14 @@ destination can be easily changed, as shown in the example below::
|
||||
|
||||
logging.basicConfig(level=logging.DEBUG,
|
||||
format='%(asctime)s %(levelname)s %(message)s',
|
||||
filename='/tmp/myapp.log',
|
||||
filename='myapp.log',
|
||||
filemode='w')
|
||||
logging.debug('A debug message')
|
||||
logging.info('Some information')
|
||||
logging.warning('A shot across the bows')
|
||||
|
||||
The :meth:`basicConfig` method is used to change the configuration defaults,
|
||||
which results in output (written to ``/tmp/myapp.log``) which should look
|
||||
which results in output (written to ``myapp.log``) which should look
|
||||
something like the following::
|
||||
|
||||
2004-07-02 13:00:08,743 DEBUG A debug message
|
||||
@ -2553,19 +2604,57 @@ logging module using these functions or by making calls to the main API (defined
|
||||
in :mod:`logging` itself) and defining handlers which are declared either in
|
||||
:mod:`logging` or :mod:`logging.handlers`.
|
||||
|
||||
.. function:: dictConfig(config)
|
||||
|
||||
.. function:: fileConfig(fname, defaults=None, disable_existing_loggers=True)
|
||||
Takes the logging configuration from a dictionary. The contents of
|
||||
this dictionary are described in :ref:`logging-config-dictschema`
|
||||
below.
|
||||
|
||||
If an error is encountered during configuration, this function will
|
||||
raise a :exc:`ValueError`, :exc:`TypeError`, :exc:`AttributeError`
|
||||
or :exc:`ImportError` with a suitably descriptive message. The
|
||||
following is a (possibly incomplete) list of conditions which will
|
||||
raise an error:
|
||||
|
||||
* A ``level`` which is not a string or which is a string not
|
||||
corresponding to an actual logging level.
|
||||
* A ``propagate`` value which is not a boolean.
|
||||
* An id which does not have a corresponding destination.
|
||||
* A non-existent handler id found during an incremental call.
|
||||
* An invalid logger name.
|
||||
* Inability to resolve to an internal or external object.
|
||||
|
||||
Parsing is performed by the :class:`DictConfigurator` class, whose
|
||||
constructor is passed the dictionary used for configuration, and
|
||||
has a :meth:`configure` method. The :mod:`logging.config` module
|
||||
has a callable attribute :attr:`dictConfigClass`
|
||||
which is initially set to :class:`DictConfigurator`.
|
||||
You can replace the value of :attr:`dictConfigClass` with a
|
||||
suitable implementation of your own.
|
||||
|
||||
:func:`dictConfig` calls :attr:`dictConfigClass` passing
|
||||
the specified dictionary, and then calls the :meth:`configure` method on
|
||||
the returned object to put the configuration into effect::
|
||||
|
||||
def dictConfig(config):
|
||||
dictConfigClass(config).configure()
|
||||
|
||||
For example, a subclass of :class:`DictConfigurator` could call
|
||||
``DictConfigurator.__init__()`` in its own :meth:`__init__()`, then
|
||||
set up custom prefixes which would be usable in the subsequent
|
||||
:meth:`configure` call. :attr:`dictConfigClass` would be bound to
|
||||
this new subclass, and then :func:`dictConfig` could be called exactly as
|
||||
in the default, uncustomized state.
|
||||
|
||||
.. function:: fileConfig(fname[, defaults])
|
||||
|
||||
Reads the logging configuration from a :mod:`configparser`\-format file named
|
||||
*fname*. This function can be called several times from an application,
|
||||
allowing an end user the ability to select from various pre-canned
|
||||
allowing an end user to select from various pre-canned
|
||||
configurations (if the developer provides a mechanism to present the choices
|
||||
and load the chosen configuration). Defaults to be passed to the ConfigParser
|
||||
can be specified in the *defaults* argument.
|
||||
|
||||
If *disable_existing_loggers* is true, any existing loggers that are not
|
||||
children of named loggers will be disabled.
|
||||
|
||||
|
||||
.. function:: listen(port=DEFAULT_LOGGING_CONFIG_PORT)
|
||||
|
||||
@ -2589,6 +2678,402 @@ in :mod:`logging` itself) and defining handlers which are declared either in
|
||||
:func:`listen`.
|
||||
|
||||
|
||||
.. _logging-config-dictschema:
|
||||
|
||||
Configuration dictionary schema
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Describing a logging configuration requires listing the various
|
||||
objects to create and the connections between them; for example, you
|
||||
may create a handler named "console" and then say that the logger
|
||||
named "startup" will send its messages to the "console" handler.
|
||||
These objects aren't limited to those provided by the :mod:`logging`
|
||||
module because you might write your own formatter or handler class.
|
||||
The parameters to these classes may also need to include external
|
||||
objects such as ``sys.stderr``. The syntax for describing these
|
||||
objects and connections is defined in :ref:`logging-config-dict-connections`
|
||||
below.
|
||||
|
||||
Dictionary Schema Details
|
||||
"""""""""""""""""""""""""
|
||||
|
||||
The dictionary passed to :func:`dictConfig` must contain the following
|
||||
keys:
|
||||
|
||||
* `version` - to be set to an integer value representing the schema
|
||||
version. The only valid value at present is 1, but having this key
|
||||
allows the schema to evolve while still preserving backwards
|
||||
compatibility.
|
||||
|
||||
All other keys are optional, but if present they will be interpreted
|
||||
as described below. In all cases below where a 'configuring dict' is
|
||||
mentioned, it will be checked for the special ``'()'`` key to see if a
|
||||
custom instantiation is required. If so, the mechanism described in
|
||||
:ref:`logging-config-dict-userdef` below is used to create an instance;
|
||||
otherwise, the context is used to determine what to instantiate.
|
||||
|
||||
* `formatters` - the corresponding value will be a dict in which each
|
||||
key is a formatter id and each value is a dict describing how to
|
||||
configure the corresponding Formatter instance.
|
||||
|
||||
The configuring dict is searched for keys ``format`` and ``datefmt``
|
||||
(with defaults of ``None``) and these are used to construct a
|
||||
:class:`logging.Formatter` instance.
|
||||
|
||||
* `filters` - the corresponding value will be a dict in which each key
|
||||
is a filter id and each value is a dict describing how to configure
|
||||
the corresponding Filter instance.
|
||||
|
||||
The configuring dict is searched for the key ``name`` (defaulting to the
|
||||
empty string) and this is used to construct a :class:`logging.Filter`
|
||||
instance.
|
||||
|
||||
* `handlers` - the corresponding value will be a dict in which each
|
||||
key is a handler id and each value is a dict describing how to
|
||||
configure the corresponding Handler instance.
|
||||
|
||||
The configuring dict is searched for the following keys:
|
||||
|
||||
* ``class`` (mandatory). This is the fully qualified name of the
|
||||
handler class.
|
||||
|
||||
* ``level`` (optional). The level of the handler.
|
||||
|
||||
* ``formatter`` (optional). The id of the formatter for this
|
||||
handler.
|
||||
|
||||
* ``filters`` (optional). A list of ids of the filters for this
|
||||
handler.
|
||||
|
||||
All *other* keys are passed through as keyword arguments to the
|
||||
handler's constructor. For example, given the snippet::
|
||||
|
||||
handlers:
|
||||
console:
|
||||
class : logging.StreamHandler
|
||||
formatter: brief
|
||||
level : INFO
|
||||
filters: [allow_foo]
|
||||
stream : ext://sys.stdout
|
||||
file:
|
||||
class : logging.handlers.RotatingFileHandler
|
||||
formatter: precise
|
||||
filename: logconfig.log
|
||||
maxBytes: 1024
|
||||
backupCount: 3
|
||||
|
||||
the handler with id ``console`` is instantiated as a
|
||||
:class:`logging.StreamHandler`, using ``sys.stdout`` as the underlying
|
||||
stream. The handler with id ``file`` is instantiated as a
|
||||
:class:`logging.handlers.RotatingFileHandler` with the keyword arguments
|
||||
``filename='logconfig.log', maxBytes=1024, backupCount=3``.
|
||||
|
||||
* `loggers` - the corresponding value will be a dict in which each key
|
||||
is a logger name and each value is a dict describing how to
|
||||
configure the corresponding Logger instance.
|
||||
|
||||
The configuring dict is searched for the following keys:
|
||||
|
||||
* ``level`` (optional). The level of the logger.
|
||||
|
||||
* ``propagate`` (optional). The propagation setting of the logger.
|
||||
|
||||
* ``filters`` (optional). A list of ids of the filters for this
|
||||
logger.
|
||||
|
||||
* ``handlers`` (optional). A list of ids of the handlers for this
|
||||
logger.
|
||||
|
||||
The specified loggers will be configured according to the level,
|
||||
propagation, filters and handlers specified.
|
||||
|
||||
* `root` - this will be the configuration for the root logger.
|
||||
Processing of the configuration will be as for any logger, except
|
||||
that the ``propagate`` setting will not be applicable.
|
||||
|
||||
* `incremental` - whether the configuration is to be interpreted as
|
||||
incremental to the existing configuration. This value defaults to
|
||||
``False``, which means that the specified configuration replaces the
|
||||
existing configuration with the same semantics as used by the
|
||||
existing :func:`fileConfig` API.
|
||||
|
||||
If the specified value is ``True``, the configuration is processed
|
||||
as described in the section on :ref:`logging-config-dict-incremental`.
|
||||
|
||||
* `disable_existing_loggers` - whether any existing loggers are to be
|
||||
disabled. This setting mirrors the parameter of the same name in
|
||||
:func:`fileConfig`. If absent, this parameter defaults to ``True``.
|
||||
This value is ignored if `incremental` is ``True``.
|
||||
|
||||
.. _logging-config-dict-incremental:
|
||||
|
||||
Incremental Configuration
|
||||
"""""""""""""""""""""""""
|
||||
|
||||
It is difficult to provide complete flexibility for incremental
|
||||
configuration. For example, because objects such as filters
|
||||
and formatters are anonymous, once a configuration is set up, it is
|
||||
not possible to refer to such anonymous objects when augmenting a
|
||||
configuration.
|
||||
|
||||
Furthermore, there is not a compelling case for arbitrarily altering
|
||||
the object graph of loggers, handlers, filters, formatters at
|
||||
run-time, once a configuration is set up; the verbosity of loggers and
|
||||
handlers can be controlled just by setting levels (and, in the case of
|
||||
loggers, propagation flags). Changing the object graph arbitrarily in
|
||||
a safe way is problematic in a multi-threaded environment; while not
|
||||
impossible, the benefits are not worth the complexity it adds to the
|
||||
implementation.
|
||||
|
||||
Thus, when the ``incremental`` key of a configuration dict is present
|
||||
and is ``True``, the system will completely ignore any ``formatters`` and
|
||||
``filters`` entries, and process only the ``level``
|
||||
settings in the ``handlers`` entries, and the ``level`` and
|
||||
``propagate`` settings in the ``loggers`` and ``root`` entries.
|
||||
|
||||
Using a value in the configuration dict lets configurations to be sent
|
||||
over the wire as pickled dicts to a socket listener. Thus, the logging
|
||||
verbosity of a long-running application can be altered over time with
|
||||
no need to stop and restart the application.
|
||||
|
||||
.. _logging-config-dict-connections:
|
||||
|
||||
Object connections
|
||||
""""""""""""""""""
|
||||
|
||||
The schema describes a set of logging objects - loggers,
|
||||
handlers, formatters, filters - which are connected to each other in
|
||||
an object graph. Thus, the schema needs to represent connections
|
||||
between the objects. For example, say that, once configured, a
|
||||
particular logger has attached to it a particular handler. For the
|
||||
purposes of this discussion, we can say that the logger represents the
|
||||
source, and the handler the destination, of a connection between the
|
||||
two. Of course in the configured objects this is represented by the
|
||||
logger holding a reference to the handler. In the configuration dict,
|
||||
this is done by giving each destination object an id which identifies
|
||||
it unambiguously, and then using the id in the source object's
|
||||
configuration to indicate that a connection exists between the source
|
||||
and the destination object with that id.
|
||||
|
||||
So, for example, consider the following YAML snippet::
|
||||
|
||||
formatters:
|
||||
brief:
|
||||
# configuration for formatter with id 'brief' goes here
|
||||
precise:
|
||||
# configuration for formatter with id 'precise' goes here
|
||||
handlers:
|
||||
h1: #This is an id
|
||||
# configuration of handler with id 'h1' goes here
|
||||
formatter: brief
|
||||
h2: #This is another id
|
||||
# configuration of handler with id 'h2' goes here
|
||||
formatter: precise
|
||||
loggers:
|
||||
foo.bar.baz:
|
||||
# other configuration for logger 'foo.bar.baz'
|
||||
handlers: [h1, h2]
|
||||
|
||||
(Note: YAML used here because it's a little more readable than the
|
||||
equivalent Python source form for the dictionary.)
|
||||
|
||||
The ids for loggers are the logger names which would be used
|
||||
programmatically to obtain a reference to those loggers, e.g.
|
||||
``foo.bar.baz``. The ids for Formatters and Filters can be any string
|
||||
value (such as ``brief``, ``precise`` above) and they are transient,
|
||||
in that they are only meaningful for processing the configuration
|
||||
dictionary and used to determine connections between objects, and are
|
||||
not persisted anywhere when the configuration call is complete.
|
||||
|
||||
The above snippet indicates that logger named ``foo.bar.baz`` should
|
||||
have two handlers attached to it, which are described by the handler
|
||||
ids ``h1`` and ``h2``. The formatter for ``h1`` is that described by id
|
||||
``brief``, and the formatter for ``h2`` is that described by id
|
||||
``precise``.
|
||||
|
||||
|
||||
.. _logging-config-dict-userdef:
|
||||
|
||||
User-defined objects
|
||||
""""""""""""""""""""
|
||||
|
||||
The schema supports user-defined objects for handlers, filters and
|
||||
formatters. (Loggers do not need to have different types for
|
||||
different instances, so there is no support in this configuration
|
||||
schema for user-defined logger classes.)
|
||||
|
||||
Objects to be configured are described by dictionaries
|
||||
which detail their configuration. In some places, the logging system
|
||||
will be able to infer from the context how an object is to be
|
||||
instantiated, but when a user-defined object is to be instantiated,
|
||||
the system will not know how to do this. In order to provide complete
|
||||
flexibility for user-defined object instantiation, the user needs
|
||||
to provide a 'factory' - a callable which is called with a
|
||||
configuration dictionary and which returns the instantiated object.
|
||||
This is signalled by an absolute import path to the factory being
|
||||
made available under the special key ``'()'``. Here's a concrete
|
||||
example::
|
||||
|
||||
formatters:
|
||||
brief:
|
||||
format: '%(message)s'
|
||||
default:
|
||||
format: '%(asctime)s %(levelname)-8s %(name)-15s %(message)s'
|
||||
datefmt: '%Y-%m-%d %H:%M:%S'
|
||||
custom:
|
||||
(): my.package.customFormatterFactory
|
||||
bar: baz
|
||||
spam: 99.9
|
||||
answer: 42
|
||||
|
||||
The above YAML snippet defines three formatters. The first, with id
|
||||
``brief``, is a standard :class:`logging.Formatter` instance with the
|
||||
specified format string. The second, with id ``default``, has a
|
||||
longer format and also defines the time format explicitly, and will
|
||||
result in a :class:`logging.Formatter` initialized with those two format
|
||||
strings. Shown in Python source form, the ``brief`` and ``default``
|
||||
formatters have configuration sub-dictionaries::
|
||||
|
||||
{
|
||||
'format' : '%(message)s'
|
||||
}
|
||||
|
||||
and::
|
||||
|
||||
{
|
||||
'format' : '%(asctime)s %(levelname)-8s %(name)-15s %(message)s',
|
||||
'datefmt' : '%Y-%m-%d %H:%M:%S'
|
||||
}
|
||||
|
||||
respectively, and as these dictionaries do not contain the special key
|
||||
``'()'``, the instantiation is inferred from the context: as a result,
|
||||
standard :class:`logging.Formatter` instances are created. The
|
||||
configuration sub-dictionary for the third formatter, with id
|
||||
``custom``, is::
|
||||
|
||||
{
|
||||
'()' : 'my.package.customFormatterFactory',
|
||||
'bar' : 'baz',
|
||||
'spam' : 99.9,
|
||||
'answer' : 42
|
||||
}
|
||||
|
||||
and this contains the special key ``'()'``, which means that
|
||||
user-defined instantiation is wanted. In this case, the specified
|
||||
factory callable will be used. If it is an actual callable it will be
|
||||
used directly - otherwise, if you specify a string (as in the example)
|
||||
the actual callable will be located using normal import mechanisms.
|
||||
The callable will be called with the **remaining** items in the
|
||||
configuration sub-dictionary as keyword arguments. In the above
|
||||
example, the formatter with id ``custom`` will be assumed to be
|
||||
returned by the call::
|
||||
|
||||
my.package.customFormatterFactory(bar='baz', spam=99.9, answer=42)
|
||||
|
||||
The key ``'()'`` has been used as the special key because it is not a
|
||||
valid keyword parameter name, and so will not clash with the names of
|
||||
the keyword arguments used in the call. The ``'()'`` also serves as a
|
||||
mnemonic that the corresponding value is a callable.
|
||||
|
||||
|
||||
.. _logging-config-dict-externalobj:
|
||||
|
||||
Access to external objects
|
||||
""""""""""""""""""""""""""
|
||||
|
||||
There are times where a configuration needs to refer to objects
|
||||
external to the configuration, for example ``sys.stderr``. If the
|
||||
configuration dict is constructed using Python code, this is
|
||||
straightforward, but a problem arises when the configuration is
|
||||
provided via a text file (e.g. JSON, YAML). In a text file, there is
|
||||
no standard way to distinguish ``sys.stderr`` from the literal string
|
||||
``'sys.stderr'``. To facilitate this distinction, the configuration
|
||||
system looks for certain special prefixes in string values and
|
||||
treat them specially. For example, if the literal string
|
||||
``'ext://sys.stderr'`` is provided as a value in the configuration,
|
||||
then the ``ext://`` will be stripped off and the remainder of the
|
||||
value processed using normal import mechanisms.
|
||||
|
||||
The handling of such prefixes is done in a way analogous to protocol
|
||||
handling: there is a generic mechanism to look for prefixes which
|
||||
match the regular expression ``^(?P<prefix>[a-z]+)://(?P<suffix>.*)$``
|
||||
whereby, if the ``prefix`` is recognised, the ``suffix`` is processed
|
||||
in a prefix-dependent manner and the result of the processing replaces
|
||||
the string value. If the prefix is not recognised, then the string
|
||||
value will be left as-is.
|
||||
|
||||
|
||||
.. _logging-config-dict-internalobj:
|
||||
|
||||
Access to internal objects
|
||||
""""""""""""""""""""""""""
|
||||
|
||||
As well as external objects, there is sometimes also a need to refer
|
||||
to objects in the configuration. This will be done implicitly by the
|
||||
configuration system for things that it knows about. For example, the
|
||||
string value ``'DEBUG'`` for a ``level`` in a logger or handler will
|
||||
automatically be converted to the value ``logging.DEBUG``, and the
|
||||
``handlers``, ``filters`` and ``formatter`` entries will take an
|
||||
object id and resolve to the appropriate destination object.
|
||||
|
||||
However, a more generic mechanism is needed for user-defined
|
||||
objects which are not known to the :mod:`logging` module. For
|
||||
example, consider :class:`logging.handlers.MemoryHandler`, which takes
|
||||
a ``target`` argument which is another handler to delegate to. Since
|
||||
the system already knows about this class, then in the configuration,
|
||||
the given ``target`` just needs to be the object id of the relevant
|
||||
target handler, and the system will resolve to the handler from the
|
||||
id. If, however, a user defines a ``my.package.MyHandler`` which has
|
||||
an ``alternate`` handler, the configuration system would not know that
|
||||
the ``alternate`` referred to a handler. To cater for this, a generic
|
||||
resolution system allows the user to specify::
|
||||
|
||||
handlers:
|
||||
file:
|
||||
# configuration of file handler goes here
|
||||
|
||||
custom:
|
||||
(): my.package.MyHandler
|
||||
alternate: cfg://handlers.file
|
||||
|
||||
The literal string ``'cfg://handlers.file'`` will be resolved in an
|
||||
analogous way to strings with the ``ext://`` prefix, but looking
|
||||
in the configuration itself rather than the import namespace. The
|
||||
mechanism allows access by dot or by index, in a similar way to
|
||||
that provided by ``str.format``. Thus, given the following snippet::
|
||||
|
||||
handlers:
|
||||
email:
|
||||
class: logging.handlers.SMTPHandler
|
||||
mailhost: localhost
|
||||
fromaddr: my_app@domain.tld
|
||||
toaddrs:
|
||||
- support_team@domain.tld
|
||||
- dev_team@domain.tld
|
||||
subject: Houston, we have a problem.
|
||||
|
||||
in the configuration, the string ``'cfg://handlers'`` would resolve to
|
||||
the dict with key ``handlers``, the string ``'cfg://handlers.email``
|
||||
would resolve to the dict with key ``email`` in the ``handlers`` dict,
|
||||
and so on. The string ``'cfg://handlers.email.toaddrs[1]`` would
|
||||
resolve to ``'dev_team.domain.tld'`` and the string
|
||||
``'cfg://handlers.email.toaddrs[0]'`` would resolve to the value
|
||||
``'support_team@domain.tld'``. The ``subject`` value could be accessed
|
||||
using either ``'cfg://handlers.email.subject'`` or, equivalently,
|
||||
``'cfg://handlers.email[subject]'``. The latter form only needs to be
|
||||
used if the key contains spaces or non-alphanumeric characters. If an
|
||||
index value consists only of decimal digits, access will be attempted
|
||||
using the corresponding integer value, falling back to the string
|
||||
value if needed.
|
||||
|
||||
Given a string ``cfg://handlers.myhandler.mykey.123``, this will
|
||||
resolve to ``config_dict['handlers']['myhandler']['mykey']['123']``.
|
||||
If the string is specified as ``cfg://handlers.myhandler.mykey[123]``,
|
||||
the system will attempt to retrieve the value from
|
||||
``config_dict['handlers']['myhandler']['mykey'][123]``, and fall back
|
||||
to ``config_dict['handlers']['myhandler']['mykey']['123']`` if that
|
||||
fails.
|
||||
|
||||
.. _logging-config-fileformat:
|
||||
|
||||
Configuration file format
|
||||
|
||||
@ -1115,7 +1115,8 @@ Files and Directories
|
||||
|
||||
Create a directory named *path* with numeric mode *mode*. The default *mode*
|
||||
is ``0o777`` (octal). On some systems, *mode* is ignored. Where it is used,
|
||||
the current umask value is first masked out.
|
||||
the current umask value is first masked out. If the directory already
|
||||
exists, :exc:`OSError` is raised.
|
||||
|
||||
It is also possible to create temporary directories; see the
|
||||
:mod:`tempfile` module's :func:`tempfile.mkdtemp` function.
|
||||
|
||||
@ -709,18 +709,12 @@ Regular Expression Objects
|
||||
|
||||
The :class:`RegexObject` class supports the following methods and attributes:
|
||||
|
||||
.. method:: RegexObject.search(string[, pos[, endpos]])
|
||||
|
||||
.. method:: RegexObject.match(string[, pos[, endpos]])
|
||||
|
||||
If zero or more characters at the beginning of *string* match this regular
|
||||
expression, return a corresponding :class:`MatchObject` instance. Return
|
||||
``None`` if the string does not match the pattern; note that this is different
|
||||
from a zero-length match.
|
||||
|
||||
.. note::
|
||||
|
||||
If you want to locate a match anywhere in *string*, use
|
||||
:meth:`~RegexObject.search` instead.
|
||||
Scan through *string* looking for a location where this regular expression
|
||||
produces a match, and return a corresponding :class:`MatchObject` instance.
|
||||
Return ``None`` if no position in the string matches the pattern; note that this
|
||||
is different from finding a zero-length match at some point in the string.
|
||||
|
||||
The optional second parameter *pos* gives an index in the string where the
|
||||
search is to start; it defaults to ``0``. This is not completely equivalent to
|
||||
@ -732,24 +726,34 @@ Regular Expression Objects
|
||||
will be as if the string is *endpos* characters long, so only the characters
|
||||
from *pos* to ``endpos - 1`` will be searched for a match. If *endpos* is less
|
||||
than *pos*, no match will be found, otherwise, if *rx* is a compiled regular
|
||||
expression object, ``rx.match(string, 0, 50)`` is equivalent to
|
||||
``rx.match(string[:50], 0)``.
|
||||
expression object, ``rx.search(string, 0, 50)`` is equivalent to
|
||||
``rx.search(string[:50], 0)``.
|
||||
|
||||
>>> pattern = re.compile("o")
|
||||
>>> pattern.match("dog") # No match as "o" is not at the start of "dog."
|
||||
>>> pattern.match("dog", 1) # Match as "o" is the 2nd character of "dog".
|
||||
<_sre.SRE_Match object at ...>
|
||||
>>> pattern = re.compile("d")
|
||||
>>> pattern.search("dog") # Match at index 0
|
||||
<_sre.SRE_Match object at ...>
|
||||
>>> pattern.search("dog", 1) # No match; search doesn't include the "d"
|
||||
|
||||
|
||||
.. method:: RegexObject.search(string[, pos[, endpos]])
|
||||
.. method:: RegexObject.match(string[, pos[, endpos]])
|
||||
|
||||
Scan through *string* looking for a location where this regular expression
|
||||
produces a match, and return a corresponding :class:`MatchObject` instance.
|
||||
Return ``None`` if no position in the string matches the pattern; note that this
|
||||
is different from finding a zero-length match at some point in the string.
|
||||
If zero or more characters at the *beginning* of *string* match this regular
|
||||
expression, return a corresponding :class:`MatchObject` instance. Return
|
||||
``None`` if the string does not match the pattern; note that this is different
|
||||
from a zero-length match.
|
||||
|
||||
The optional *pos* and *endpos* parameters have the same meaning as for the
|
||||
:meth:`~RegexObject.match` method.
|
||||
:meth:`~RegexObject.search` method.
|
||||
|
||||
.. note::
|
||||
|
||||
If you want to locate a match anywhere in *string*, use
|
||||
:meth:`~RegexObject.search` instead.
|
||||
|
||||
>>> pattern = re.compile("o")
|
||||
>>> pattern.match("dog") # No match as "o" is not at the start of "dog".
|
||||
>>> pattern.match("dog", 1) # Match as "o" is the 2nd character of "dog".
|
||||
<_sre.SRE_Match object at ...>
|
||||
|
||||
|
||||
.. method:: RegexObject.split(string[, maxsplit=0])
|
||||
@ -759,12 +763,16 @@ Regular Expression Objects
|
||||
|
||||
.. method:: RegexObject.findall(string[, pos[, endpos]])
|
||||
|
||||
Identical to the :func:`findall` function, using the compiled pattern.
|
||||
Similar to the :func:`findall` function, using the compiled pattern, but
|
||||
also accepts optional *pos* and *endpos* parameters that limit the search
|
||||
region like for :meth:`match`.
|
||||
|
||||
|
||||
.. method:: RegexObject.finditer(string[, pos[, endpos]])
|
||||
|
||||
Identical to the :func:`finditer` function, using the compiled pattern.
|
||||
Similar to the :func:`finditer` function, using the compiled pattern, but
|
||||
also accepts optional *pos* and *endpos* parameters that limit the search
|
||||
region like for :meth:`match`.
|
||||
|
||||
|
||||
.. method:: RegexObject.sub(repl, string[, count=0])
|
||||
|
||||
@ -71,18 +71,21 @@ for use in clustered computer environments. Addresses are represented by a
|
||||
tuple, and the fields depend on the address type. The general tuple form is
|
||||
``(addr_type, v1, v2, v3 [, scope])``, where:
|
||||
|
||||
- *addr_type* is one of TIPC_ADDR_NAMESEQ, TIPC_ADDR_NAME, or
|
||||
TIPC_ADDR_ID.
|
||||
- *scope* is one of TIPC_ZONE_SCOPE, TIPC_CLUSTER_SCOPE, and
|
||||
TIPC_NODE_SCOPE.
|
||||
- If *addr_type* is TIPC_ADDR_NAME, then *v1* is the server type, *v2* is
|
||||
the port identifier, and *v3* should be 0.
|
||||
- *addr_type* is one of TIPC_ADDR_NAMESEQ, TIPC_ADDR_NAME, or
|
||||
TIPC_ADDR_ID.
|
||||
- *scope* is one of TIPC_ZONE_SCOPE, TIPC_CLUSTER_SCOPE, and
|
||||
TIPC_NODE_SCOPE.
|
||||
- If *addr_type* is TIPC_ADDR_NAME, then *v1* is the server type, *v2* is
|
||||
the port identifier, and *v3* should be 0.
|
||||
|
||||
If *addr_type* is TIPC_ADDR_NAMESEQ, then *v1* is the server type, *v2*
|
||||
is the lower port number, and *v3* is the upper port number.
|
||||
If *addr_type* is TIPC_ADDR_NAMESEQ, then *v1* is the server type, *v2*
|
||||
is the lower port number, and *v3* is the upper port number.
|
||||
|
||||
If *addr_type* is TIPC_ADDR_ID, then *v1* is the node, *v2* is the
|
||||
reference, and *v3* should be set to 0.
|
||||
If *addr_type* is TIPC_ADDR_ID, then *v1* is the node, *v2* is the
|
||||
reference, and *v3* should be set to 0.
|
||||
|
||||
If *addr_type* is TIPC_ADDR_ID, then *v1* is the node, *v2* is the
|
||||
reference, and *v3* should be set to 0.
|
||||
|
||||
|
||||
All errors raise exceptions. The normal exceptions for invalid argument types
|
||||
@ -690,7 +693,7 @@ correspond to Unix system calls applicable to sockets.
|
||||
|
||||
Set a timeout on blocking socket operations. The *value* argument can be a
|
||||
nonnegative float expressing seconds, or ``None``. If a float is given,
|
||||
subsequent socket operations will raise an :exc:`timeout` exception if the
|
||||
subsequent socket operations will raise a :exc:`timeout` exception if the
|
||||
timeout period *value* has elapsed before the operation has completed. Setting
|
||||
a timeout of ``None`` disables timeouts on socket operations.
|
||||
``s.settimeout(0.0)`` is equivalent to ``s.setblocking(0)``;
|
||||
|
||||
@ -110,13 +110,16 @@ Functions, Constants, and Exceptions
|
||||
|
||||
.. note::
|
||||
|
||||
This information varies depending on the version of OpenSSL.
|
||||
For instance, in some older versions of OpenSSL (such as 0.9.7l on
|
||||
OS X 10.4), an SSLv2 client could not connect to an SSLv23 server.
|
||||
Conversely, starting from 1.0.0, an SSLv23 client will actually
|
||||
try the SSLv3 protocol unless you explicitly enable SSLv2 ciphers.
|
||||
Which connections succeed will vary depending on the version of
|
||||
OpenSSL. For instance, in some older versions of OpenSSL (such
|
||||
as 0.9.7l on OS X 10.4), an SSLv2 client could not connect to an
|
||||
SSLv23 server. Another example: beginning with OpenSSL 1.0.0,
|
||||
an SSLv23 client will not actually attempt SSLv2 connections
|
||||
unless you explicitly enable SSLv2 ciphers; for example, you
|
||||
might specify ``"ALL"`` or ``"SSLv2"`` as the *ciphers* parameter
|
||||
to enable them.
|
||||
|
||||
The parameter ``ciphers`` sets the available ciphers for this SSL object.
|
||||
The *ciphers* parameter sets the available ciphers for this SSL object.
|
||||
It should be a string in the `OpenSSL cipher list format
|
||||
<http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT>`_.
|
||||
|
||||
|
||||
@ -1329,6 +1329,10 @@ functions based on regular expressions.
|
||||
You can use :meth:`str.maketrans` to create a translation map from
|
||||
character-to-character mappings in different formats.
|
||||
|
||||
You can use the :func:`~string.maketrans` helper function in the :mod:`string`
|
||||
module to create a translation table. For string objects, set the *table*
|
||||
argument to ``None`` for translations that only delete characters:
|
||||
|
||||
.. note::
|
||||
|
||||
An even more flexible approach is to create a custom character mapping
|
||||
@ -2295,7 +2299,7 @@ is generally interpreted as simple bytes.
|
||||
File "<stdin>", line 1, in <module>
|
||||
ValueError: cannot modify size of memoryview object
|
||||
|
||||
Notice how the size of the memoryview object can not be changed.
|
||||
Notice how the size of the memoryview object cannot be changed.
|
||||
|
||||
|
||||
:class:`memoryview` has two methods:
|
||||
|
||||
@ -197,7 +197,7 @@ The grammar for a replacement field is as follows:
|
||||
.. productionlist:: sf
|
||||
replacement_field: "{" [`field_name`] ["!" `conversion`] [":" `format_spec`] "}"
|
||||
field_name: arg_name ("." `attribute_name` | "[" `element_index` "]")*
|
||||
arg_name: (`identifier` | `integer`)?
|
||||
arg_name: [`identifier` | `integer`]
|
||||
attribute_name: `identifier`
|
||||
element_index: `integer` | `index_string`
|
||||
index_string: <any source character except "]"> +
|
||||
|
||||
@ -16,9 +16,9 @@ relevant for the current platform.
|
||||
Configuration variables
|
||||
-----------------------
|
||||
|
||||
A Python distribution contains a :file:`Makefile` file and a :file:`python.h`
|
||||
that are necessary to build the Python binary itself, but also any C extension
|
||||
created in a third party project and compiled using :mod:`distutils`.
|
||||
A Python distribution contains a :file:`Makefile` and a :file:`pyconfig.h`
|
||||
header file that are necessary to build both the Python binary itself and
|
||||
third-party C extensions compiled using :mod:`distutils`.
|
||||
|
||||
:mod:`sysconfig` puts all variables found in these files in a dictionary that
|
||||
can be accessed using :func:`get_config_vars` or :func:`get_config_var`.
|
||||
|
||||
@ -220,26 +220,26 @@ failfast, catch and buffer command line options
|
||||
|
||||
unittest supports three command options.
|
||||
|
||||
* -f / --failfast
|
||||
* :option:`-b` / :option:`--buffer`
|
||||
|
||||
Stop the test run on the first error or failure.
|
||||
|
||||
* -c / --catch
|
||||
|
||||
Control-c during the test run waits for the current test to end and then
|
||||
reports all the results so far. A second control-c raises the normal
|
||||
``KeyboardInterrupt`` exception.
|
||||
|
||||
See `Signal Handling`_ for the functions that provide this functionality.
|
||||
|
||||
* -b / --buffer
|
||||
|
||||
The standard out and standard error streams are buffered during the test
|
||||
The standard output and standard error streams are buffered during the test
|
||||
run. Output during a passing test is discarded. Output is echoed normally
|
||||
on test fail or error and is added to the failure messages.
|
||||
|
||||
* :option:`-c` / :option:`--catch`
|
||||
|
||||
Control-C during the test run waits for the current test to end and then
|
||||
reports all the results so far. A second control-C raises the normal
|
||||
:exc:`KeyboardInterrupt` exception.
|
||||
|
||||
See `Signal Handling`_ for the functions that provide this functionality.
|
||||
|
||||
* :option:`-f` / :option:`--failfast`
|
||||
|
||||
Stop the test run on the first error or failure.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
The command line options ``-c``, ``-b`` and ``-f`` where added.
|
||||
The command line options ``-c``, ``-b`` and ``-f`` were added.
|
||||
|
||||
The command line can also be used for test discovery, for running all of the
|
||||
tests in a project or just a subset.
|
||||
@ -270,8 +270,9 @@ The ``discover`` sub-command has the following options:
|
||||
-t directory Top level directory of project (default to
|
||||
start directory)
|
||||
|
||||
The -s, -p, & -t options can be passsed in as positional arguments. The
|
||||
following two command lines are equivalent::
|
||||
The :option:`-s`, :option:`-p`, and :option:`-t` options can be passed in
|
||||
as positional arguments in that order. The following two command lines
|
||||
are equivalent::
|
||||
|
||||
python -m unittest discover -s project_directory -p '*_test.py'
|
||||
python -m unittest discover project_directory '*_test.py'
|
||||
@ -829,6 +830,11 @@ Test cases
|
||||
compare equal, the test will fail with the explanation given by *msg*, or
|
||||
:const:`None`.
|
||||
|
||||
If *delta* is supplied instead of *places* then the difference
|
||||
between *first* and *second* must be less than *delta*.
|
||||
|
||||
Supplying both *delta* and *places* raises a ``TypeError``.
|
||||
|
||||
.. versionchanged:: 3.2
|
||||
Objects that compare equal are automatically almost equal.
|
||||
Added the ``delta`` keyword argument.
|
||||
@ -849,7 +855,7 @@ Test cases
|
||||
compare equal, the test will fail with the explanation given by *msg*, or
|
||||
:const:`None`.
|
||||
|
||||
If *delta* is supplied instead of *places* then the the difference
|
||||
If *delta* is supplied instead of *places* then the difference
|
||||
between *first* and *second* must be more than *delta*.
|
||||
|
||||
Supplying both *delta* and *places* raises a ``TypeError``.
|
||||
@ -1902,12 +1908,12 @@ instead of as an error.
|
||||
Signal Handling
|
||||
---------------
|
||||
|
||||
The -c / --catch command line option to unittest, along with the ``catchbreak``
|
||||
The :option:`-c`/:option:`--catch` command line option to unittest, along with the ``catchbreak``
|
||||
parameter to :func:`unittest.main()`, provide more friendly handling of
|
||||
control-c during a test run. With catch break behavior enabled control-c will
|
||||
control-C during a test run. With catch break behavior enabled control-C will
|
||||
allow the currently running test to complete, and the test run will then end
|
||||
and report all the results so far. A second control-c will raise a
|
||||
``KeyboardInterrupt`` in the usual way.
|
||||
:exc:`KeyboardInterrupt` in the usual way.
|
||||
|
||||
The control-c handling signal handler attempts to remain compatible with code or
|
||||
tests that install their own :const:`signal.SIGINT` handler. If the ``unittest``
|
||||
|
||||
@ -1595,7 +1595,7 @@ The following methods are used to override the default behavior of the
|
||||
|
||||
In particular, the metaclass :class:`abc.ABCMeta` implements these methods in
|
||||
order to allow the addition of Abstract Base Classes (ABCs) as "virtual base
|
||||
classes" to any class or type (including built-in types), and including to other
|
||||
classes" to any class or type (including built-in types), including other
|
||||
ABCs.
|
||||
|
||||
.. method:: class.__instancecheck__(self, instance)
|
||||
@ -1614,7 +1614,7 @@ ABCs.
|
||||
|
||||
Note that these methods are looked up on the type (metaclass) of a class. They
|
||||
cannot be defined as class methods in the actual class. This is consistent with
|
||||
the lookup of special methods that are called on instances, only that in this
|
||||
the lookup of special methods that are called on instances, only in this
|
||||
case the instance is itself a class.
|
||||
|
||||
.. seealso::
|
||||
|
||||
@ -69,12 +69,12 @@ IronPython
|
||||
more information, see `the IronPython website <http://www.ironpython.com/>`_.
|
||||
|
||||
PyPy
|
||||
An implementation of Python written in Python; even the bytecode interpreter is
|
||||
written in Python. This is executed using CPython as the underlying
|
||||
interpreter. One of the goals of the project is to encourage experimentation
|
||||
with the language itself by making it easier to modify the interpreter (since it
|
||||
is written in Python). Additional information is available on `the PyPy
|
||||
project's home page <http://codespeak.net/pypy/>`_.
|
||||
An implementation of Python written completely in Python. It supports several
|
||||
advanced features not found in other implementations like stackless support
|
||||
and a Just in Time compiler. One of the goals of the project is to encourage
|
||||
experimentation with the language itself by making it easier to modify the
|
||||
interpreter (since it is written in Python). Additional information is
|
||||
available on `the PyPy project's home page <http://pypy.org/>`_.
|
||||
|
||||
Each of these implementations varies in some way from the language as documented
|
||||
in this manual, or introduces specific information beyond what's covered in the
|
||||
|
||||
@ -580,7 +580,7 @@ Private Variables
|
||||
=================
|
||||
|
||||
"Private" instance variables that cannot be accessed except from inside an
|
||||
object, don't exist in Python. However, there is a convention that is followed
|
||||
object don't exist in Python. However, there is a convention that is followed
|
||||
by most Python code: a name prefixed with an underscore (e.g. ``_spam``) should
|
||||
be treated as a non-public part of the API (whether it is a function, a method
|
||||
or a data member). It should be considered an implementation detail and subject
|
||||
|
||||
@ -208,7 +208,7 @@ next line is a logical continuation of the line::
|
||||
|
||||
print(hello)
|
||||
|
||||
Note that newlines still need to be embedded in the string using ``\n``; the
|
||||
Note that newlines still need to be embedded in the string using ``\n`` -- the
|
||||
newline following the trailing backslash is discarded. This example would print
|
||||
the following:
|
||||
|
||||
|
||||
@ -114,8 +114,8 @@ The IDE
|
||||
=======
|
||||
|
||||
MacPython ships with the standard IDLE development environment. A good
|
||||
introduction to using IDLE can be found at http://hkn.eecs.berkeley.edu/
|
||||
dyoo/python/idle_intro/index.html.
|
||||
introduction to using IDLE can be found at
|
||||
http://hkn.eecs.berkeley.edu/~dyoo/python/idle_intro/index.html.
|
||||
|
||||
|
||||
.. _mac-package-manager:
|
||||
|
||||
1279
Doc/whatsnew/2.7.rst
1279
Doc/whatsnew/2.7.rst
File diff suppressed because it is too large
Load Diff
@ -8,21 +8,22 @@ and L. Masinter, January 2005.
|
||||
RFC 2732 : "Format for Literal IPv6 Addresses in URL's by R.Hinden, B.Carpenter
|
||||
and L.Masinter, December 1999.
|
||||
|
||||
RFC2396: "Uniform Resource Identifiers (URI)": Generic Syntax by T.
|
||||
RFC 2396: "Uniform Resource Identifiers (URI)": Generic Syntax by T.
|
||||
Berners-Lee, R. Fielding, and L. Masinter, August 1998.
|
||||
|
||||
RFC2368: "The mailto URL scheme", by P.Hoffman , L Masinter, J. Zwinski, July 1998.
|
||||
RFC 2368: "The mailto URL scheme", by P.Hoffman , L Masinter, J. Zwinski, July 1998.
|
||||
|
||||
RFC 1808: "Relative Uniform Resource Locators", by R. Fielding, UC Irvine, June
|
||||
1995.
|
||||
|
||||
RFC1738: "Uniform Resource Locators (URL)" by T. Berners-Lee, L. Masinter, M.
|
||||
RFC 1738: "Uniform Resource Locators (URL)" by T. Berners-Lee, L. Masinter, M.
|
||||
McCahill, December 1994
|
||||
|
||||
RFC 3986 is considered the current standard and any changes to urlparse module
|
||||
should conform to this. urlparse module is not entirely compliant with this.
|
||||
The defacto scenarios of parsing are considered sometimes and for backward
|
||||
compatiblity purposes, older RFC uses of parsing are retained. The testcases in
|
||||
RFC 3986 is considered the current standard and any future changes to
|
||||
urlparse module should conform with it. The urlparse module is
|
||||
currently not entirely compliant with this RFC due to defacto
|
||||
scenarios for parsing, and for backward compatibility purposes, some
|
||||
parsing quirks from older RFCs are retained. The testcases in
|
||||
test_urlparse.py provides a good indicator of parsing behavior.
|
||||
"""
|
||||
|
||||
|
||||
@ -3277,7 +3277,8 @@ static PyMethodDef tzinfo_methods[] = {
|
||||
PyDoc_STR("datetime -> DST offset in minutes east of UTC.")},
|
||||
|
||||
{"fromutc", (PyCFunction)tzinfo_fromutc, METH_O,
|
||||
PyDoc_STR("datetime in UTC -> datetime in local time.")},
|
||||
PyDoc_STR("datetime -> timedelta showing offset from UTC, negative "
|
||||
"values indicating West of UTC")},
|
||||
|
||||
{"__reduce__", (PyCFunction)tzinfo_reduce, METH_NOARGS,
|
||||
PyDoc_STR("-> (cls, state)")},
|
||||
|
||||
Loading…
Reference in New Issue
Block a user