summaryrefslogtreecommitdiffstats
path: root/Python/peephole.c
diff options
context:
space:
mode:
Diffstat (limited to 'Python/peephole.c')
-rw-r--r--Python/peephole.c16
1 files changed, 10 insertions, 6 deletions
diff --git a/Python/peephole.c b/Python/peephole.c
index f2e0c0b..7c4640c 100644
--- a/Python/peephole.c
+++ b/Python/peephole.c
@@ -1,4 +1,4 @@
-/* Peehole optimizations for bytecode compiler. */
+/* Peephole optimizations for bytecode compiler. */
#include "Python.h"
@@ -380,13 +380,17 @@ PyCode_Optimize(PyObject *code, PyObject* consts, PyObject *names,
if (name == NULL || strcmp(name, "None") != 0)
continue;
for (j=0 ; j < PyList_GET_SIZE(consts) ; j++) {
- if (PyList_GET_ITEM(consts, j) == Py_None) {
- codestr[i] = LOAD_CONST;
- SETARG(codestr, i, j);
- cumlc = lastlc + 1;
+ if (PyList_GET_ITEM(consts, j) == Py_None)
break;
- }
}
+ if (j == PyList_GET_SIZE(consts)) {
+ if (PyList_Append(consts, Py_None) == -1)
+ goto exitUnchanged;
+ }
+ assert(PyList_GET_ITEM(consts, j) == Py_None);
+ codestr[i] = LOAD_CONST;
+ SETARG(codestr, i, j);
+ cumlc = lastlc + 1;
break;
/* Skip over LOAD_CONST trueconst
Lib/test/output/test_cProfile | 12 +- Lib/test/output/test_profile | 12 +- PC/VS7.1/Uninstal.wse | 514 ++++++ PC/VS7.1/_bsddb.vcproj | 258 +++ PC/VS7.1/_ctypes.vcproj | 311 ++++ PC/VS7.1/_ctypes_test.vcproj | 242 +++ PC/VS7.1/_elementtree.vcproj | 264 +++ PC/VS7.1/_msi.vcproj | 252 +++ PC/VS7.1/_socket.vcproj | 254 +++ PC/VS7.1/_sqlite3.vcproj | 283 +++ PC/VS7.1/_ssl.mak | 38 + PC/VS7.1/_ssl.vcproj | 84 + PC/VS7.1/_testcapi.vcproj | 247 +++ PC/VS7.1/_tkinter.vcproj | 261 +++ PC/VS7.1/amd64_ml64.bat | 17 + PC/VS7.1/build_ssl.bat | 12 + PC/VS7.1/build_ssl.py | 181 ++ PC/VS7.1/bz2.vcproj | 271 +++ PC/VS7.1/db.build | 10 + PC/VS7.1/field3.py | 35 + PC/VS7.1/installer.bmp | Bin 0 -> 58806 bytes PC/VS7.1/make_buildinfo.c | 92 + PC/VS7.1/make_buildinfo.vcproj | 122 ++ PC/VS7.1/make_versioninfo.vcproj | 142 ++ PC/VS7.1/pcbuild.sln | 288 +++ PC/VS7.1/pyexpat.vcproj | 263 +++ PC/VS7.1/python.build | 21 + PC/VS7.1/python.iss | 346 ++++ PC/VS7.1/python.vcproj | 274 +++ PC/VS7.1/python20.wse | 3135 ++++++++++++++++++++++++++++++++ PC/VS7.1/pythoncore.vcproj | 806 ++++++++ PC/VS7.1/pythonw.vcproj | 261 +++ PC/VS7.1/readme.txt | 426 +++++ PC/VS7.1/rmpyc.py | 25 + PC/VS7.1/rt.bat | 52 + PC/VS7.1/select.vcproj | 258 +++ PC/VS7.1/unicodedata.vcproj | 247 +++ PC/VS7.1/w9xpopen.vcproj | 121 ++ PC/VS7.1/winsound.vcproj | 251 +++ PCbuild/Uninstal.wse | 514 ------ PCbuild/_bsddb.vcproj | 631 +++++-- PCbuild/_ctypes.vcproj | 825 ++++++--- PCbuild/_ctypes_test.vcproj | 591 ++++-- PCbuild/_elementtree.vcproj | 697 +++++-- PCbuild/_msi.vcproj | 597 ++++-- PCbuild/_socket.vcproj | 603 ++++-- PCbuild/_sqlite3.vcproj | 740 ++++++-- PCbuild/_ssl.mak | 38 - PCbuild/_ssl.vcproj | 581 +++++- PCbuild/_testcapi.vcproj | 592 ++++-- PCbuild/_tkinter.vcproj | 634 +++++-- PCbuild/amd64_ml64.bat | 17 - PCbuild/bdist_wininst.vcproj | 177 ++ PCbuild/build.bat | 63 +- PCbuild/build_env.bat | 2 +- PCbuild/build_pgo.bat | 41 + PCbuild/build_ssl.bat | 26 +- PCbuild/build_ssl.py | 141 +- PCbuild/build_tkinter.py | 86 + PCbuild/bz2.vcproj | 634 +++++-- PCbuild/db.build | 10 - PCbuild/debug.vsprops | 11 + PCbuild/env.bat | 25 +- PCbuild/idle.bat | 15 + PCbuild/make_buildinfo.c | 26 +- PCbuild/make_buildinfo.vcproj | 170 +- PCbuild/make_versioninfo.vcproj | 330 +++- PCbuild/pcbuild.sln | 609 ++++--- PCbuild/pginstrument.vsprops | 34 + PCbuild/pgupdate.vsprops | 14 + PCbuild/pyd.vsprops | 22 + PCbuild/pyd_d.vsprops | 30 + PCbuild/pyexpat.vcproj | 644 +++++-- PCbuild/pyproject.vsprops | 79 + PCbuild/python.build | 21 - PCbuild/python.iss | 337 ---- PCbuild/python.vcproj | 669 +++++-- PCbuild/python20.wse | 3127 ------------------------------- PCbuild/pythoncore.vcproj | 2271 ++++++++++++++++------- PCbuild/pythonw.vcproj | 649 +++++-- PCbuild/readme.txt | 374 ++-- PCbuild/release.vsprops | 11 + PCbuild/rt.bat | 0 PCbuild/select.vcproj | 605 ++++-- PCbuild/unicodedata.vcproj | 604 ++++-- PCbuild/w9xpopen.vcproj | 577 +++++- PCbuild/winsound.vcproj | 594 ++++-- PCbuild/x64.vsprops | 18 + PCbuild9/_bsddb.vcproj | 553 ------ PCbuild9/_ctypes.vcproj | 704 ------- PCbuild9/_ctypes_test.vcproj | 521 ------ PCbuild9/_elementtree.vcproj | 621 ------- PCbuild9/_msi.vcproj | 529 ------ PCbuild9/_socket.vcproj | 537 ------ PCbuild9/_sqlite3.vcproj | 637 ------- PCbuild9/_ssl.vcproj | 549 ------ PCbuild9/_testcapi.vcproj | 521 ------ PCbuild9/_tkinter.vcproj | 541 ------ PCbuild9/build.bat | 17 - PCbuild9/build_env.bat | 1 - PCbuild9/build_pgo.bat | 41 - PCbuild9/build_ssl.bat | 12 - PCbuild9/build_ssl.py | 250 --- PCbuild9/build_tkinter.py | 86 - PCbuild9/bz2.vcproj | 545 ------ PCbuild9/debug.vsprops | 11 - PCbuild9/env.bat | 5 - PCbuild9/field3.py | 35 - PCbuild9/idle.bat | 15 - PCbuild9/installer.bmp | Bin 58806 -> 0 bytes PCbuild9/make_buildinfo.c | 94 - PCbuild9/make_buildinfo.vcproj | 162 -- PCbuild9/make_versioninfo.vcproj | 326 ---- PCbuild9/pcbuild.sln | 461 ----- PCbuild9/pginstrument.vsprops | 34 - PCbuild9/pgupdate.vsprops | 14 - PCbuild9/pyd.vsprops | 22 - PCbuild9/pyd_d.vsprops | 30 - PCbuild9/pyexpat.vcproj | 553 ------ PCbuild9/pyproject.vsprops | 79 - PCbuild9/python.vcproj | 645 ------- PCbuild9/pythoncore.vcproj | 1773 ------------------ PCbuild9/pythonw.vcproj | 618 ------- PCbuild9/readme.txt | 334 ---- PCbuild9/release.vsprops | 11 - PCbuild9/rmpyc.py | 25 - PCbuild9/rt.bat | 52 - PCbuild9/select.vcproj | 537 ------ PCbuild9/unicodedata.vcproj | 533 ------ PCbuild9/w9xpopen.vcproj | 576 ------ PCbuild9/winsound.vcproj | 523 ------ PCbuild9/x64.vsprops | 18 - Tools/buildbot/build-amd64.bat | 2 +- Tools/buildbot/build.bat | 2 +- Tools/buildbot/buildmsi.bat | 2 +- Tools/buildbot/clean-amd64.bat | 2 +- Tools/buildbot/clean.bat | 2 +- Tools/buildbot/kill_python.c | 8 +- Tools/buildbot/test-amd64.bat | 2 +- Tools/buildbot/test.bat | 2 +- Tools/msi/msi.py | 2 +- configure | 21 +- configure.in | 11 +- 267 files changed, 23518 insertions(+), 23481 deletions(-) create mode 100644 Lib/distutils/command/wininst-6.0.exe delete mode 100644 Lib/distutils/command/wininst-6.exe create mode 100644 Lib/distutils/command/wininst-8.0.exe delete mode 100644 Lib/distutils/command/wininst-8.exe create mode 100644 Lib/distutils/command/wininst-9.0.exe create mode 100644 PC/VS7.1/Uninstal.wse create mode 100644 PC/VS7.1/_bsddb.vcproj create mode 100644 PC/VS7.1/_ctypes.vcproj create mode 100644 PC/VS7.1/_ctypes_test.vcproj create mode 100644 PC/VS7.1/_elementtree.vcproj create mode 100644 PC/VS7.1/_msi.vcproj create mode 100644 PC/VS7.1/_socket.vcproj create mode 100644 PC/VS7.1/_sqlite3.vcproj create mode 100644 PC/VS7.1/_ssl.mak create mode 100644 PC/VS7.1/_ssl.vcproj create mode 100644 PC/VS7.1/_testcapi.vcproj create mode 100644 PC/VS7.1/_tkinter.vcproj create mode 100644 PC/VS7.1/amd64_ml64.bat create mode 100644 PC/VS7.1/build_ssl.bat create mode 100644 PC/VS7.1/build_ssl.py create mode 100644 PC/VS7.1/bz2.vcproj create mode 100644 PC/VS7.1/db.build create mode 100644 PC/VS7.1/field3.py create mode 100644 PC/VS7.1/installer.bmp create mode 100644 PC/VS7.1/make_buildinfo.c create mode 100644 PC/VS7.1/make_buildinfo.vcproj create mode 100644 PC/VS7.1/make_versioninfo.vcproj create mode 100644 PC/VS7.1/pcbuild.sln create mode 100644 PC/VS7.1/pyexpat.vcproj create mode 100644 PC/VS7.1/python.build create mode 100644 PC/VS7.1/python.iss create mode 100644 PC/VS7.1/python.vcproj create mode 100644 PC/VS7.1/python20.wse create mode 100644 PC/VS7.1/pythoncore.vcproj create mode 100644 PC/VS7.1/pythonw.vcproj create mode 100644 PC/VS7.1/readme.txt create mode 100644 PC/VS7.1/rmpyc.py create mode 100755 PC/VS7.1/rt.bat create mode 100644 PC/VS7.1/select.vcproj create mode 100644 PC/VS7.1/unicodedata.vcproj create mode 100644 PC/VS7.1/w9xpopen.vcproj create mode 100644 PC/VS7.1/winsound.vcproj delete mode 100644 PCbuild/Uninstal.wse delete mode 100644 PCbuild/_ssl.mak delete mode 100644 PCbuild/amd64_ml64.bat create mode 100644 PCbuild/bdist_wininst.vcproj create mode 100644 PCbuild/build_pgo.bat create mode 100644 PCbuild/build_tkinter.py delete mode 100644 PCbuild/db.build create mode 100644 PCbuild/debug.vsprops create mode 100644 PCbuild/idle.bat create mode 100644 PCbuild/pginstrument.vsprops create mode 100644 PCbuild/pgupdate.vsprops create mode 100644 PCbuild/pyd.vsprops create mode 100644 PCbuild/pyd_d.vsprops create mode 100644 PCbuild/pyproject.vsprops delete mode 100644 PCbuild/python.build delete mode 100644 PCbuild/python.iss delete mode 100644 PCbuild/python20.wse create mode 100644 PCbuild/release.vsprops mode change 100755 => 100644 PCbuild/rt.bat create mode 100644 PCbuild/x64.vsprops delete mode 100644 PCbuild9/_bsddb.vcproj delete mode 100644 PCbuild9/_ctypes.vcproj delete mode 100644 PCbuild9/_ctypes_test.vcproj delete mode 100644 PCbuild9/_elementtree.vcproj delete mode 100644 PCbuild9/_msi.vcproj delete mode 100644 PCbuild9/_socket.vcproj delete mode 100644 PCbuild9/_sqlite3.vcproj delete mode 100644 PCbuild9/_ssl.vcproj delete mode 100644 PCbuild9/_testcapi.vcproj delete mode 100644 PCbuild9/_tkinter.vcproj delete mode 100644 PCbuild9/build.bat delete mode 100644 PCbuild9/build_env.bat delete mode 100644 PCbuild9/build_pgo.bat delete mode 100644 PCbuild9/build_ssl.bat delete mode 100644 PCbuild9/build_ssl.py delete mode 100644 PCbuild9/build_tkinter.py delete mode 100644 PCbuild9/bz2.vcproj delete mode 100644 PCbuild9/debug.vsprops delete mode 100644 PCbuild9/env.bat delete mode 100644 PCbuild9/field3.py delete mode 100644 PCbuild9/idle.bat delete mode 100644 PCbuild9/installer.bmp delete mode 100644 PCbuild9/make_buildinfo.c delete mode 100644 PCbuild9/make_buildinfo.vcproj delete mode 100644 PCbuild9/make_versioninfo.vcproj delete mode 100644 PCbuild9/pcbuild.sln delete mode 100644 PCbuild9/pginstrument.vsprops delete mode 100644 PCbuild9/pgupdate.vsprops delete mode 100644 PCbuild9/pyd.vsprops delete mode 100644 PCbuild9/pyd_d.vsprops delete mode 100644 PCbuild9/pyexpat.vcproj delete mode 100644 PCbuild9/pyproject.vsprops delete mode 100644 PCbuild9/python.vcproj delete mode 100644 PCbuild9/pythoncore.vcproj delete mode 100644 PCbuild9/pythonw.vcproj delete mode 100644 PCbuild9/readme.txt delete mode 100644 PCbuild9/release.vsprops delete mode 100644 PCbuild9/rmpyc.py delete mode 100644 PCbuild9/rt.bat delete mode 100644 PCbuild9/select.vcproj delete mode 100644 PCbuild9/unicodedata.vcproj delete mode 100644 PCbuild9/w9xpopen.vcproj delete mode 100644 PCbuild9/winsound.vcproj delete mode 100644 PCbuild9/x64.vsprops diff --git a/.hgsvnexternals b/.hgsvnexternals index 048f7c8..28567dc 100644 --- a/.hgsvnexternals +++ b/.hgsvnexternals @@ -1,3 +1,2 @@ [Tools] 2to3 http://svn.python.org/projects/sandbox/trunk/2to3/ - diff --git a/Doc/Makefile b/Doc/Makefile index 22f852b..189a2f7 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -16,10 +16,11 @@ ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees -D latex_paper_size=$(PAPER) \ help: @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " web to make file usable by Sphinx.web" + @echo " html to make standalone HTML files" + @echo " web to make file usable by Sphinx.web" @echo " htmlhelp to make HTML files and a HTML help project" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " changes to make an overview over all changed/added/deprecated items" checkout: @if [ ! -d tools/sphinx ]; then \ @@ -66,6 +67,10 @@ latex: build @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ "run these through (pdf)latex." +changes: BUILDER = changes +changes: build + @echo "The overview file is in build/changes." + clean: -rm -rf build/* -rm -rf tools/sphinx diff --git a/Doc/README.txt b/Doc/README.txt index 9db4f4c..c6f685c 100644 --- a/Doc/README.txt +++ b/Doc/README.txt @@ -56,6 +56,10 @@ Available make targets are: * "latex", which builds LaTeX source files that can be run with "pdflatex" to produce PDF documents. + * "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. + A "make update" updates the Subversion checkouts in `tools/`. diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index 9413762..3e06e4f 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -31,8 +31,8 @@ The error indicator consists of three Python objects corresponding to the result of ``sys.exc_info()``. API functions exist to interact with the error indicator in various ways. There is a separate error indicator for each thread. -.. % XXX Order of these should be more thoughtful. -.. % Either alphabetical or some kind of structure. +.. XXX Order of these should be more thoughtful. + Either alphabetical or some kind of structure. .. cfunction:: void PyErr_Print() diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index a4f25fa..dac37e1 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -264,7 +264,7 @@ Initialization, Finalization, and Threads as the list ``sys.path``, which may be modified to change the future search path for loaded modules. - .. % XXX should give the exact rules + .. XXX should give the exact rules .. cfunction:: const char* Py_GetVersion() @@ -357,8 +357,8 @@ Initialization, Finalization, and Threads to initialize ``sys.argv``, a fatal condition is signalled using :cfunc:`Py_FatalError`. - .. % XXX impl. doesn't seem consistent in allowing 0/NULL for the params; - .. % check w/ Guido. + .. XXX impl. doesn't seem consistent in allowing 0/NULL for the params; + check w/ Guido. .. _threads: diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index 54412cd..2742a53 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -484,7 +484,7 @@ Here is the corresponding C code, in all its glory:: single: PyErr_Clear() single: Py_XDECREF() -This example represents an endorsed use of the :keyword:`goto` statement in C! +This example represents an endorsed use of the ``goto`` statement in C! It illustrates the use of :cfunc:`PyErr_ExceptionMatches` and :cfunc:`PyErr_Clear` to handle specific exceptions, and the use of :cfunc:`Py_XDECREF` to dispose of owned references that may be *NULL* (note the diff --git a/Doc/c-api/newtypes.rst b/Doc/c-api/newtypes.rst index b557957..88a4f2f 100644 --- a/Doc/c-api/newtypes.rst +++ b/Doc/c-api/newtypes.rst @@ -459,7 +459,7 @@ type objects) *must* have the :attr:`ob_size` field. declare the instance struct) and this in turn includes the :attr:`_ob_prev` and :attr:`_ob_next` fields if they are present. This means that the only correct way to get an initializer for the :attr:`tp_basicsize` is to use the - :keyword:`sizeof` operator on the struct used to declare the instance layout. + ``sizeof`` operator on the struct used to declare the instance layout. The basic size does not include the GC header size (this is new in Python 2.2; in 2.1 and 2.0, the GC header size was included in :attr:`tp_basicsize`). @@ -1145,7 +1145,7 @@ The next fields, up to and including :attr:`tp_weaklist`, only exist if the PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type); - XXX more + XXX explain. This field is inherited by subtypes. @@ -1160,7 +1160,7 @@ The next fields, up to and including :attr:`tp_weaklist`, only exist if the This field is inherited by subtypes. - XXX more + XXX explain. .. cmember:: long PyTypeObject.tp_dictoffset @@ -1683,10 +1683,9 @@ member in the :ctype:`PyTypeObject` structure should be *NULL*. Otherwise, the and :exc:`SystemError` should be raised when *segment* specifies a segment that doesn't exist. - .. % Why doesn't it raise ValueError for this one? - .. % GJS: because you shouldn't be calling it with an invalid - .. % segment. That indicates a blatant programming error in the C - .. % code. + .. Why doesn't it raise ValueError for this one? + GJS: because you shouldn't be calling it with an invalid + segment. That indicates a blatant programming error in the C code. .. ctype:: Py_ssize_t (*segcountproc) (PyObject *self, Py_ssize_t *lenp) diff --git a/Doc/distutils/setupscript.rst b/Doc/distutils/setupscript.rst index 3ffcc78..8b88b58 100644 --- a/Doc/distutils/setupscript.rst +++ b/Doc/distutils/setupscript.rst @@ -137,7 +137,7 @@ the Distutils to go out and find the right files; you have to specify the extension name, source file(s), and any compile/link requirements (include directories, libraries to link with, etc.). -.. % XXX read over this section +.. XXX read over this section All of this is done through another keyword argument to :func:`setup`, the :option:`ext_modules` option. :option:`ext_modules` is just a list of diff --git a/Doc/documenting/fromlatex.rst b/Doc/documenting/fromlatex.rst index 42045f7..116524a 100644 --- a/Doc/documenting/fromlatex.rst +++ b/Doc/documenting/fromlatex.rst @@ -154,25 +154,35 @@ These changes to information units should be noted: Description. -* **New information unit** +* **New information units** - There is a new generic information unit called "describe" which can be used - to document things that are not covered by the other units:: + There are new generic information units: One is called "describe" and can be + used to document things that are not covered by the other units:: .. describe:: a == b The equals operator. + The others are:: + + .. cmdoption:: -O + + Describes a command-line option. + + .. envvar:: PYTHONINSPECT + + Describes an environment variable. + Structure --------- -The LaTeX docs were split in several toplevel manuals. Now, all files -are part of the same documentation tree, as indicated by the *toctree* -directives in the sources. Every *toctree* directive embeds other files -as subdocuments of the current file (this structure is not necessarily -mirrored in the filesystem layout). The toplevel file is -:file:`contents.rst`. +The LaTeX docs were split in several toplevel manuals. Now, all files are part +of the same documentation tree, as indicated by the *toctree* directives in the +sources (though individual output formats may choose to split them up into parts +again). Every *toctree* directive embeds other files as subdocuments of the +current file (this structure is not necessarily mirrored in the filesystem +layout). The toplevel file is :file:`contents.rst`. However, most of the old directory structure has been kept, with the directories renamed as follows: @@ -184,7 +194,7 @@ directories renamed as follows: * :file:`inst` -> :file:`installing` * :file:`lib` -> :file:`library` * :file:`mac` -> merged into :file:`library`, with :file:`mac/using.tex` - moved to :file:`howto/pythonmac.rst` + moved to :file:`using/mac.rst` * :file:`ref` -> :file:`reference` * :file:`tut` -> :file:`tutorial`, with the single TeX file split up diff --git a/Doc/documenting/markup.rst b/Doc/documenting/markup.rst index a246d62..f3a8237 100644 --- a/Doc/documenting/markup.rst +++ b/Doc/documenting/markup.rst @@ -455,7 +455,7 @@ in a different style: .. describe:: keyword - The name of a keyword in a programming language. + The name of a keyword in Python. .. describe:: mailheader diff --git a/Doc/documenting/sphinx.rst b/Doc/documenting/sphinx.rst index 85e8b5e..43da14e 100644 --- a/Doc/documenting/sphinx.rst +++ b/Doc/documenting/sphinx.rst @@ -47,14 +47,30 @@ unused_files : list of strings could be docs for temporarily disabled modules or documentation that's not yet ready for public consumption. -last_updated_format : string +add_function_parentheses : bool + If true, ``()`` will be appended to the content of ``:func:``, ``:meth:`` and + ``:cfunc:`` cross-references. + +add_module_names : bool + If true, the current module name will be prepended to all description unit + titles (such as ``.. function::``). + +Builder-specific variables +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +html_download_base_url : string + The base URL for download links on the download page. + +html_last_updated_fmt : string If this is not an empty string, it will be given to ``time.strftime()`` and written to each generated output file after "last updated on:". -use_smartypants : bool +html_use_smartypants : bool If true, use SmartyPants to convert quotes and dashes to the typographically correct entities. -add_function_parentheses : bool - If true, ``()`` will be appended to the content of ``:func:``, ``:meth:`` and - ``:cfunc:`` cross-references. \ No newline at end of file +latex_paper_size : "letter" or "a4" + The paper size option for the LaTeX document class. + +latex_font_size : "10pt", "11pt" or "12pt" + The font size option for the LaTeX document class. \ No newline at end of file diff --git a/Doc/extending/embedding.rst b/Doc/extending/embedding.rst index a50c008..6ba2c67 100644 --- a/Doc/extending/embedding.rst +++ b/Doc/extending/embedding.rst @@ -155,11 +155,7 @@ then the result should be:: Although the program is quite large for its functionality, most of the code is for data conversion between Python and C, and for error reporting. The -interesting part with respect to embedding Python starts with - -.. % $ - -:: +interesting part with respect to embedding Python starts with :: Py_Initialize(); pName = PyString_FromString(argv[1]); @@ -239,15 +235,8 @@ With these extensions, the Python script can do things like :: In a real application, the methods will expose an API of the application to Python. -.. % \section{For the future} -.. % -.. % You don't happen to have a nice library to get textual -.. % equivalents of numeric values do you :-) ? -.. % Callbacks here ? (I may be using information from that section -.. % ?!) -.. % threads -.. % code examples do not really behave well if errors happen -.. % (what to watch out for) +.. TODO: threads, code examples do not really behave well if errors happen + (what to watch out for) .. _embeddingincplusplus: diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst index 9b5e0fe..5459a7d 100644 --- a/Doc/extending/extending.rst +++ b/Doc/extending/extending.rst @@ -306,7 +306,7 @@ function. The method table must be passed to the interpreter in the module's initialization function. The initialization function must be named :cfunc:`initname`, where *name* is the name of the module, and should be the -only non-\ :keyword:`static` item defined in the module file:: +only non-\ ``static`` item defined in the module file:: PyMODINIT_FUNC initspam(void) @@ -660,11 +660,7 @@ it returns false and raises an appropriate exception. .. index:: single: Philbrick, Geoff Here is an example module which uses keywords, based on an example by Geoff -Philbrick (philbrick@hks.com): - -.. % - -:: +Philbrick (philbrick@hks.com):: #include "Python.h" @@ -762,8 +758,8 @@ Reference Counts In languages like C or C++, the programmer is responsible for dynamic allocation and deallocation of memory on the heap. In C, this is done using the functions -:cfunc:`malloc` and :cfunc:`free`. In C++, the operators :keyword:`new` and -:keyword:`delete` are used with essentially the same meaning and we'll restrict +:cfunc:`malloc` and :cfunc:`free`. In C++, the operators ``new`` and +``delete`` are used with essentially the same meaning and we'll restrict the following discussion to the C case. Every block of memory allocated with :cfunc:`malloc` should eventually be @@ -1036,11 +1032,10 @@ that it is always a tuple. [#]_ It is a severe error to ever let a *NULL* pointer "escape" to the Python user. -.. % Frank Stajano: -.. % A pedagogically buggy example, along the lines of the previous listing, -.. % would be helpful here -- showing in more concrete terms what sort of -.. % actions could cause the problem. I can't very well imagine it from the -.. % description. +.. Frank Stajano: + A pedagogically buggy example, along the lines of the previous listing, would + be helpful here -- showing in more concrete terms what sort of actions could + cause the problem. I can't very well imagine it from the description. .. _cplusplus: @@ -1076,7 +1071,7 @@ lists, this new collection type should have a set of C functions for direct manipulation from other extension modules. At first sight this seems easy: just write the functions (without declaring them -:keyword:`static`, of course), provide an appropriate header file, and document +``static``, of course), provide an appropriate header file, and document the C API. And in fact this would work if all extension modules were always linked statically with the Python interpreter. When modules are used as shared libraries, however, the symbols defined in one module may not be visible to @@ -1089,7 +1084,7 @@ the module whose functions one wishes to call might not have been loaded yet! Portability therefore requires not to make any assumptions about symbol visibility. This means that all symbols in extension modules should be declared -:keyword:`static`, except for the module's initialization function, in order to +``static``, except for the module's initialization function, in order to avoid name clashes with other extension modules (as discussed in section :ref:`methodtable`). And it means that symbols that *should* be accessible from other extension modules must be exported in a different way. @@ -1124,7 +1119,7 @@ reality (such as adding "spam" to every command). This function :cfunc:`PySpam_System` is also exported to other extension modules. The function :cfunc:`PySpam_System` is a plain C function, declared -:keyword:`static` like everything else:: +``static`` like everything else:: static int PySpam_System(const char *command) @@ -1180,7 +1175,7 @@ function must take care of initializing the C API pointer array:: PyModule_AddObject(m, "_C_API", c_api_object); } -Note that ``PySpam_API`` is declared :keyword:`static`; otherwise the pointer +Note that ``PySpam_API`` is declared ``static``; otherwise the pointer array would disappear when :func:`initspam` terminates! The bulk of the work is in the header file :file:`spammodule.h`, which looks diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst index e2cf6df..cbe3b68 100644 --- a/Doc/extending/newtypes.rst +++ b/Doc/extending/newtypes.rst @@ -1196,16 +1196,14 @@ class object, and get the doc string using its :attr:`__doc__` attribute. As with the :attr:`tp_methods` table, a sentinel entry with a :attr:`name` value of *NULL* is required. -.. % XXX Descriptors need to be explained in more detail somewhere, but -.. % not here. -.. % -.. % Descriptor objects have two handler functions which correspond to -.. % the \member{tp_getattro} and \member{tp_setattro} handlers. The -.. % \method{__get__()} handler is a function which is passed the -.. % descriptor, instance, and type objects, and returns the value of the -.. % attribute, or it returns \NULL{} and sets an exception. The -.. % \method{__set__()} handler is passed the descriptor, instance, type, -.. % and new value; +.. XXX Descriptors need to be explained in more detail somewhere, but not here. + + Descriptor objects have two handler functions which correspond to the + \member{tp_getattro} and \member{tp_setattro} handlers. The + \method{__get__()} handler is a function which is passed the descriptor, + instance, and type objects, and returns the value of the attribute, or it + returns \NULL{} and sets an exception. The \method{__set__()} handler is + passed the descriptor, instance, type, and new value; Type-specific Attribute Management diff --git a/Doc/extending/windows.rst b/Doc/extending/windows.rst index 7a66afe..a34ba2b 100644 --- a/Doc/extending/windows.rst +++ b/Doc/extending/windows.rst @@ -7,8 +7,6 @@ Building C and C++ Extensions on Windows **************************************** -.. % - This chapter briefly explains how to create a Windows extension module for Python using Microsoft Visual C++, and follows with more detailed background information on how it works. The explanatory material is useful for both the diff --git a/Doc/howto/advocacy.rst b/Doc/howto/advocacy.rst index 1f1754a..7d7706e 100644 --- a/Doc/howto/advocacy.rst +++ b/Doc/howto/advocacy.rst @@ -302,11 +302,11 @@ http://www.pythonology.com/success The Python Success Stories are a collection of stories from successful users of Python, with the emphasis on business and corporate users. -.. % \term{\url{http://www.fsbassociates.com/books/pythonchpt1.htm}} -.. % The first chapter of \emph{Internet Programming with Python} also -.. % examines some of the reasons for using Python. The book is well worth -.. % buying, but the publishers have made the first chapter available on -.. % the Web. +.. http://www.fsbassociates.com/books/pythonchpt1.htm + The first chapter of \emph{Internet Programming with Python} also + examines some of the reasons for using Python. The book is well worth + buying, but the publishers have made the first chapter available on + the Web. http://home.pacbell.net/ouster/scripting.html John Ousterhout's white paper on scripting is a good argument for the utility of @@ -333,9 +333,9 @@ http://pythonjournal.cognizor.com/pyj1/Everitt-Feit_interview98-V1.html to show that choosing Python didn't introduce any difficulties into a company's development process, and provided some substantial benefits. -.. % \term{\url{http://www.python.org/psa/Commercial.html}} -.. % Robin Friedrich wrote this document on how to support Python's use in -.. % commercial projects. +.. http://www.python.org/psa/Commercial.html + Robin Friedrich wrote this document on how to support Python's use in + commercial projects. http://www.python.org/workshops/1997-10/proceedings/stein.ps For the 6th Python conference, Greg Stein presented a paper that traced Python's diff --git a/Doc/howto/doanddont.rst b/Doc/howto/doanddont.rst index ace5bed..0e6b3e8 100644 --- a/Doc/howto/doanddont.rst +++ b/Doc/howto/doanddont.rst @@ -291,7 +291,7 @@ are often more then is comfortable to put in one line, many people do:: calculate_number(10, 20) != forbulate(500, 360): pass -You should realize that this is dangerous: a stray space after the ``XXX`` would +You should realize that this is dangerous: a stray space after the ``\`` would make this line wrong, and stray spaces are notoriously hard to see in editors. In this case, at least it would be a syntax error, but if the code was:: diff --git a/Doc/howto/regex.rst b/Doc/howto/regex.rst index 783bec1..6adecd7 100644 --- a/Doc/howto/regex.rst +++ b/Doc/howto/regex.rst @@ -5,11 +5,11 @@ :Author: A.M. Kuchling :Release: 0.05 -.. % TODO: -.. % Document lookbehind assertions -.. % Better way of displaying a RE, a string, and what it matches -.. % Mention optional argument to match.groups() -.. % Unicode (at least a reference) +.. TODO: + Document lookbehind assertions + Better way of displaying a RE, a string, and what it matches + Mention optional argument to match.groups() + Unicode (at least a reference) .. topic:: Abstract @@ -91,8 +91,6 @@ is the same as ``[a-c]``, which uses a range to express the same set of characters. If you wanted to match only lowercase letters, your RE would be ``[a-z]``. -.. % $ - Metacharacters are not active inside classes. For example, ``[akm$]`` will match any of the characters ``'a'``, ``'k'``, ``'m'``, or ``'$'``; ``'$'`` is usually a metacharacter, but inside a character class it's stripped of its @@ -679,8 +677,8 @@ given location, they can obviously be matched an infinite number of times. >>> print(re.search('^From', 'Reciting From Memory')) None - .. % To match a literal \character{\^}, use \regexp{\e\^} or enclose it - .. % inside a character class, as in \regexp{[{\e}\^]}. + .. To match a literal \character{\^}, use \regexp{\e\^} or enclose it + .. inside a character class, as in \regexp{[{\e}\^]}. ``$`` Matches at the end of a line, which is defined as either the end of the string, @@ -696,8 +694,6 @@ given location, they can obviously be matched an infinite number of times. To match a literal ``'$'``, use ``\$`` or enclose it inside a character class, as in ``[$]``. - .. % $ - ``\A`` Matches only at the start of the string. When not in :const:`MULTILINE` mode, ``\A`` and ``^`` are effectively the same. In :const:`MULTILINE` mode, they're @@ -980,12 +976,8 @@ filenames where the extension is not ``bat``? Some incorrect attempts: that the first character of the extension is not a ``b``. This is wrong, because the pattern also doesn't match ``foo.bar``. -.. % $ - ``.*[.]([^b]..|.[^a].|..[^t])$`` -.. % Messes up the HTML without the curly braces around \^ - The expression gets messier when you try to patch up the first solution by requiring one of the following cases to match: the first character of the extension isn't ``b``; the second character isn't ``a``; or the third character @@ -1013,16 +1005,12 @@ match, the whole pattern will fail. The trailing ``$`` is required to ensure that something like ``sample.batch``, where the extension only starts with ``bat``, will be allowed. -.. % $ - Excluding another filename extension is now easy; simply add it as an alternative inside the assertion. The following pattern excludes filenames that end in either ``bat`` or ``exe``: ``.*[.](?!bat$|exe$).*$`` -.. % $ - Modifying Strings ================= @@ -1343,16 +1331,10 @@ enables REs to be formatted more neatly:: \s*$ # Trailing whitespace to end-of-line """, re.VERBOSE) -This is far more readable than: - -.. % $ - -:: +This is far more readable than:: pat = re.compile(r"\s*(?P
[^:]+)\s*:(?P.*?)\s*$") -.. % $ - Feedback ======== diff --git a/Doc/install/index.rst b/Doc/install/index.rst index 1bfc703..c830c8d 100644 --- a/Doc/install/index.rst +++ b/Doc/install/index.rst @@ -10,18 +10,17 @@ :Release: |version| :Date: |today| -.. % TODO: -.. % Fill in XXX comments - -.. % The audience for this document includes people who don't know anything -.. % about Python and aren't about to learn the language just in order to -.. % install and maintain it for their users, i.e. system administrators. -.. % Thus, I have to be sure to explain the basics at some point: -.. % sys.path and PYTHONPATH at least. Should probably give pointers to -.. % other docs on "import site", PYTHONSTARTUP, PYTHONHOME, etc. -.. % -.. % Finally, it might be useful to include all the material from my "Care -.. % and Feeding of a Python Installation" talk in here somewhere. Yow! +.. TODO: Fill in XXX comments + +.. The audience for this document includes people who don't know anything + about Python and aren't about to learn the language just in order to + install and maintain it for their users, i.e. system administrators. + Thus, I have to be sure to explain the basics at some point: + sys.path and PYTHONPATH at least. Should probably give pointers to + other docs on "import site", PYTHONSTARTUP, PYTHONHOME, etc. + + Finally, it might be useful to include all the material from my "Care + and Feeding of a Python Installation" talk in here somewhere. Yow! .. topic:: Abstract @@ -565,11 +564,11 @@ environment variables, such as Mac OS 9, the configuration variables supplied by the Distutils are the only ones you can use.) See section :ref:`inst-config-files` for details. -.. % XXX need some Windows examples---when would custom -.. % installation schemes be needed on those platforms? +.. XXX need some Windows examples---when would custom installation schemes be + needed on those platforms? -.. % XXX I'm not sure where this section should go. +.. XXX I'm not sure where this section should go. .. _inst-search-path: @@ -881,8 +880,8 @@ Microsoft Visual C++, which uses COFF as the object file format.) For this reason you have to convert Python's library :file:`python25.lib` into the Borland format. You can do this as follows: -.. % Should we mention that users have to create cfg-files for the compiler? -.. % see also http://community.borland.com/article/0,1410,21205,00.html +.. Should we mention that users have to create cfg-files for the compiler? +.. see also http://community.borland.com/article/0,1410,21205,00.html :: @@ -940,8 +939,8 @@ a good program for this task at http://starship.python.net/crew/kernr/mingw32/Notes.html, see at PExports 0.42h there.) -.. % I don't understand what the next line means. --amk -.. % (inclusive the references on data structures.) +.. I don't understand what the next line means. --amk +.. (inclusive the references on data structures.) :: diff --git a/Doc/library/aepack.rst b/Doc/library/aepack.rst index 0ee93e5..daaa9b2 100644 --- a/Doc/library/aepack.rst +++ b/Doc/library/aepack.rst @@ -6,9 +6,7 @@ :platform: Mac :synopsis: Conversion between Python variables and AppleEvent data containers. .. sectionauthor:: Vincent Marchetti - - -.. % \moduleauthor{Jack Jansen?}{email} +.. moduleauthor:: Jack Jansen The :mod:`aepack` module defines functions for converting (packing) Python variables to AppleEvent descriptors and back (unpacking). Within Python the diff --git a/Doc/library/aetools.rst b/Doc/library/aetools.rst index b5fd4ad..da427eb 100644 --- a/Doc/library/aetools.rst +++ b/Doc/library/aetools.rst @@ -6,9 +6,7 @@ :platform: Mac :synopsis: Basic support for sending Apple Events .. sectionauthor:: Jack Jansen - - -.. % \moduleauthor{Jack Jansen?}{email} +.. moduleauthor:: Jack Jansen The :mod:`aetools` module contains the basic functionality on which Python AppleScript client support is built. It also imports and re-exports the core diff --git a/Doc/library/aetypes.rst b/Doc/library/aetypes.rst index 0dd0a88..c8c5d80 100644 --- a/Doc/library/aetypes.rst +++ b/Doc/library/aetypes.rst @@ -6,9 +6,7 @@ :platform: Mac :synopsis: Python representation of the Apple Event Object Model. .. sectionauthor:: Vincent Marchetti - - -.. % \moduleauthor{Jack Jansen?}{email} +.. moduleauthor:: Jack Jansen The :mod:`aetypes` defines classes used to represent Apple Event data descriptors and Apple Event object specifiers. diff --git a/Doc/library/asyncore.rst b/Doc/library/asyncore.rst index 2ed3c92..6830bae 100644 --- a/Doc/library/asyncore.rst +++ b/Doc/library/asyncore.rst @@ -8,13 +8,12 @@ .. moduleauthor:: Sam Rushing .. sectionauthor:: Christopher Petrilli .. sectionauthor:: Steve Holden +.. heavily adapted from original documentation by Sam Rushing This module provides the basic infrastructure for writing asynchronous socket service clients and servers. -.. % Heavily adapted from original documentation by Sam Rushing. - There are only two ways to have a program on a single processor do "more than one thing at a time." Multi-threaded programming is the simplest and most popular way to do it, but there is another very different technique, that lets diff --git a/Doc/library/audioop.rst b/Doc/library/audioop.rst index 7779610..8ee2795 100644 --- a/Doc/library/audioop.rst +++ b/Doc/library/audioop.rst @@ -19,7 +19,7 @@ specified otherwise. 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... +.. 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. diff --git a/Doc/library/bisect.rst b/Doc/library/bisect.rst index 10f72fb..114300e 100644 --- a/Doc/library/bisect.rst +++ b/Doc/library/bisect.rst @@ -5,11 +5,7 @@ .. module:: bisect :synopsis: Array bisection algorithms for binary searching. .. sectionauthor:: Fred L. Drake, Jr. - - -.. % LaTeX produced by Fred L. Drake, Jr. , with an -.. % example based on the PyModules FAQ entry by Aaron Watters -.. % . +.. example based on the PyModules FAQ entry by Aaron Watters 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 diff --git a/Doc/library/cgi.rst b/Doc/library/cgi.rst index 41ebf9d..9f0171c 100644 --- a/Doc/library/cgi.rst +++ b/Doc/library/cgi.rst @@ -176,7 +176,7 @@ 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 ? +.. 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 diff --git a/Doc/library/codeop.rst b/Doc/library/codeop.rst index 35430b4..456f6dd 100644 --- a/Doc/library/codeop.rst +++ b/Doc/library/codeop.rst @@ -7,9 +7,6 @@ .. sectionauthor:: Moshe Zadka .. sectionauthor:: Michael Hudson - -.. % LaTeXed from excellent doc-string. - The :mod:`codeop` module provides utilities upon which the Python read-eval-print loop can be emulated, as is done in the :mod:`code` module. As a result, you probably don't want to use the module directly; if you want to @@ -29,7 +26,6 @@ of doing them both. To do just the former: - .. function:: compile_command(source[, filename[, symbol]]) Tries to compile *source*, which should be a string of Python code and return a diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index e01c52e..3fd0cc9 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -100,7 +100,7 @@ particular functionality, for example:: where only the most recent activity is of interest. .. versionchanged:: 2.6 - Added *maxlen* + Added *maxlen* parameter. Deque objects support the following methods: diff --git a/Doc/library/configparser.rst b/Doc/library/configparser.rst index 6185aa0..979f351 100644 --- a/Doc/library/configparser.rst +++ b/Doc/library/configparser.rst @@ -87,7 +87,7 @@ write-back, as will be the keys within each section. well. New applications should prefer this version if they don't need to be compatible with older versions of Python. - .. % XXX Need to explain what's safer/more predictable about it. + .. XXX Need to explain what's safer/more predictable about it. .. exception:: NoSectionError diff --git a/Doc/library/constants.rst b/Doc/library/constants.rst index 0d44b7b..3870874 100644 --- a/Doc/library/constants.rst +++ b/Doc/library/constants.rst @@ -15,19 +15,21 @@ A small number of constants live in the built-in namespace. They are: .. data:: False - The false value of the :class:`bool` type. + 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. + The true value of the :class:`bool` type. Assignments to ``True`` + are illegal and raise a :exc:`SyntaxError`. .. data:: None The sole value of :attr:`types.NoneType`. ``None`` is frequently used to represent the absence of a value, as when default arguments are not passed to a - function. + function. Assignments to ``None`` are illegal and raise a :exc:`SyntaxError`. .. data:: NotImplemented @@ -42,11 +44,11 @@ A small number of constants live in the built-in namespace. They are: The same as ``...``. Special value used mostly in conjunction with extended slicing syntax for user-defined container data types, as in :: - val = container[1:5, 7:10, ...] + .. XXX Someone who understands extended slicing should fill in here. .. data:: __debug__ - A boolean value that is :data:`True` if Python was not started with the - ``-O`` command line option. Its value is used indirectly by the - :keyword:`assert` statement, but it can also be used directly in code. + This constant is true if Python was not started with an :option:`-O` option. + Assignments to :const:`__debug__` are illegal and raise a :exc:`SyntaxError`. + See also the :keyword:`assert` statement. diff --git a/Doc/library/copy.rst b/Doc/library/copy.rst index 0abee4d..485cfc5 100644 --- a/Doc/library/copy.rst +++ b/Doc/library/copy.rst @@ -21,8 +21,6 @@ Interface summary:: For module specific errors, :exc:`copy.error` is raised. -.. % - The difference between shallow and deep copying is only relevant for compound objects (objects that contain other objects, like lists or class instances): diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index c759832..bbe4408 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -69,7 +69,7 @@ the library by creating an instance of CDLL by calling the constructor:: >>> -.. % XXX Add section for Mac OS X. +.. XXX Add section for Mac OS X. .. _ctypes-accessing-functions-from-loaded-dlls: @@ -1256,10 +1256,6 @@ Enumeration types are not implemented. You can do it easily yourself, using ``long double`` is not implemented. -.. % Local Variables: -.. % compile-command: "make.bat" -.. % End: - .. _ctypes-ctypes-reference: diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst index 046b796..07ccc55 100644 --- a/Doc/library/curses.rst +++ b/Doc/library/curses.rst @@ -1167,7 +1167,7 @@ Several constants are available to specify character cell attributes: Keys are referred to by integer constants with names starting with ``KEY_``. The exact keycaps available are system dependent. -.. % XXX should this table be alphabetized? +.. XXX this table is far too large! should it be alphabetized? +-------------------+--------------------------------------------+ | Key constant | Key | diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index adc1664..3fad2fb 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -1,6 +1,3 @@ -.. % XXX what order should the types be discussed in? - - :mod:`datetime` --- Basic date and time types ============================================= @@ -10,6 +7,7 @@ .. sectionauthor:: Tim Peters .. sectionauthor:: A.M. Kuchling +.. XXX what order should the types be discussed in? The :mod:`datetime` module supplies classes for manipulating dates and times in both simple and complex ways. While date and time arithmetic is supported, the @@ -202,7 +200,7 @@ Instance attributes (read-only): Supported operations: -.. % XXX this table is too wide! +.. XXX this table is too wide! +--------------------------------+-----------------------------------------------+ | Operation | Result | diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index fecfdeb..218d1c8 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -88,7 +88,7 @@ reset them before monitoring a calculation. * IEEE standard 854-1987, `Unofficial IEEE 854 Text `_. -.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% .. _decimal-tutorial: @@ -263,7 +263,7 @@ a single cast inside a loop. With context set and decimals created, the bulk of the program manipulates the data no differently than with other Python numeric types. -.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% .. _decimal-decimal: @@ -274,7 +274,7 @@ Decimal objects .. class:: Decimal([value [, context]]) - Constructs a new :class:`Decimal` object based from *value*. + Construct a new :class:`Decimal` object based from *value*. *value* can be an integer, string, tuple, or another :class:`Decimal` object. If no *value* is given, returns ``Decimal("0")``. If *value* is a string, it @@ -512,7 +512,7 @@ also have a number of specialized methods: correctly rounded using the :const:`ROUND_HALF_EVEN` rounding mode. -.. method: Decimal.logb([context]) +.. method:: Decimal.logb([context]) For a nonzero number, return the adjusted exponent of its operand as a :class:`Decimal` instance. If the operand is a zero then @@ -624,7 +624,7 @@ also have a number of specialized methods: .. method:: Decimal.quantize(exp[, rounding[, context[, watchexp]]]) - Returns a value equal to the first operand after rounding and + Return a value equal to the first operand after rounding and having the exponent of the second operand. >>> Decimal("1.41421356").quantize(Decimal("1.000")) @@ -645,8 +645,8 @@ also have a number of specialized methods: the given ``context`` argument; if neither argument is given the rounding mode of the current thread's context is used. - If watchexp is set (default), then an error is returned whenever - the resulting exponent is greater than Emax or less than Etiny. + If *watchexp* is set (default), then an error is returned whenever the + resulting exponent is greater than :attr:`Emax` or less than :attr:`Etiny`. .. method:: Decimal.radix() @@ -657,7 +657,7 @@ also have a number of specialized methods: .. method:: Decimal.remainder_near(other[, context]) - Computes the modulo as either a positive or negative value depending on which is + Compute the modulo as either a positive or negative value depending on which is closest to zero. For instance, ``Decimal(10).remainder_near(6)`` returns ``Decimal("-2")`` which is closer to zero than ``Decimal("4")``. @@ -720,7 +720,7 @@ also have a number of specialized methods: .. method:: Decimal.to_integral_exact([rounding[, context]]) - Round the argument to the nearest integer, signaling + Round to the nearest integer, signaling :const:`Inexact` or :const:`Rounded` as appropriate if rounding occurs. The rounding mode is determined by the ``rounding`` parameter if given, else by the given ``context``. If neither @@ -730,14 +730,14 @@ also have a number of specialized methods: .. method:: Decimal.to_integral_value([rounding[, context]]) - Rounds to the nearest integer without signaling :const:`Inexact` or + Round to the nearest integer without signaling :const:`Inexact` or :const:`Rounded`. If given, applies *rounding*; otherwise, uses the rounding method in either the supplied *context* or the current context. .. method:: Decimal.trim() - Returns its argument with *insignificant* trailing zeros removed. + Return the decimal with *insignificant* trailing zeros removed. Here, a trailing zero is considered insignificant either if it follows the decimal point, or if the exponent of the argument (that is, the last element of the :meth:`as_tuple` representation) is @@ -755,7 +755,7 @@ operands*. A *logical operand* is a :class:`Decimal` instance whose exponent and sign are both zero, and whose digits are all either :const:`0` or :const:`1`. -.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% .. _decimal-context: @@ -1023,7 +1023,7 @@ those for the :class:`Decimal` class and are only briefly recounted here. Converts a number to a string using scientific notation. -.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% .. _decimal-signals: @@ -1144,7 +1144,7 @@ The following table summarizes the hierarchy of signals:: Rounded Subnormal -.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% .. _decimal-notes: @@ -1241,7 +1241,7 @@ the following calculation returns a value equal to zero:: >>> 1 / Decimal('Infinity') Decimal("0E-1000000026") -.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% .. _decimal-threads: @@ -1279,7 +1279,7 @@ threads calling :func:`getcontext`. For example:: t3.start() . . . -.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% .. _decimal-recipes: @@ -1435,7 +1435,7 @@ to work with the :class:`Decimal` class:: return +s -.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% .. _decimal-faq: diff --git a/Doc/library/difflib.rst b/Doc/library/difflib.rst index fe956b2..3b17d04 100644 --- a/Doc/library/difflib.rst +++ b/Doc/library/difflib.rst @@ -6,9 +6,9 @@ :synopsis: Helpers for computing differences between objects. .. moduleauthor:: Tim Peters .. sectionauthor:: Tim Peters +.. Markup by Fred L. Drake, Jr. -.. % LaTeXification by Fred L. Drake, Jr. . This module provides classes and functions for comparing sequences. It can be used for example, for comparing files, and can produce difference @@ -378,6 +378,12 @@ use :meth:`set_seq2` to set the commonly used sequence once and call then ``i+n != i'`` or ``j+n != j'``; in other words, adjacent triples always describe non-adjacent equal blocks. + .. XXX Explain why a dummy is used! + + .. versionchanged:: 2.5 + The guarantee that adjacent triples always describe non-adjacent blocks was + implemented. + :: >>> s = SequenceMatcher(None, "abxcd", "abcd") diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 2616295..41cbe7f 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -452,13 +452,6 @@ the more significant byte last. Unpacks TOS into *count* individual values, which are put onto the stack right-to-left. -.. % \begin{opcodedesc}{UNPACK_LIST}{count} -.. % This opcode is obsolete. -.. % \end{opcodedesc} -.. % \begin{opcodedesc}{UNPACK_ARG}{count} -.. % This opcode is obsolete. -.. % \end{opcodedesc} - .. opcode:: DUP_TOPX (count) @@ -486,10 +479,6 @@ the more significant byte last. Works as ``DELETE_NAME``, but deletes a global name. -.. % \begin{opcodedesc}{UNPACK_VARARG}{argc} -.. % This opcode is obsolete. -.. % \end{opcodedesc} - .. opcode:: LOAD_CONST (consti) @@ -577,22 +566,11 @@ the more significant byte last. the iterator indicates it is exhausted ``TOS`` is popped, and the byte code counter is incremented by *delta*. -.. % \begin{opcodedesc}{FOR_LOOP}{delta} -.. % This opcode is obsolete. -.. % \end{opcodedesc} -.. % \begin{opcodedesc}{LOAD_LOCAL}{namei} -.. % This opcode is obsolete. -.. % \end{opcodedesc} - .. opcode:: LOAD_GLOBAL (namei) Loads the global named ``co_names[namei]`` onto the stack. -.. % \begin{opcodedesc}{SET_FUNC_ARGS}{argc} -.. % This opcode is obsolete. -.. % \end{opcodedesc} - .. opcode:: SETUP_LOOP (delta) @@ -690,7 +668,7 @@ the more significant byte last. Pushes a slice object on the stack. *argc* must be 2 or 3. If it is 2, ``slice(TOS1, TOS)`` is pushed; if it is 3, ``slice(TOS2, TOS1, TOS)`` is - pushed. See the ``slice()`` built-in function for more information. + pushed. See the :func:`slice` built-in function for more information. .. opcode:: EXTENDED_ARG (ext) diff --git a/Doc/library/dl.rst b/Doc/library/dl.rst index ff42619..de641e3 100644 --- a/Doc/library/dl.rst +++ b/Doc/library/dl.rst @@ -7,9 +7,6 @@ :synopsis: Call C functions in shared objects. .. sectionauthor:: Moshe Zadka - -.. % ?????????? Anyone???????????? - The :mod:`dl` module defines an interface to the :cfunc:`dlopen` function, which is the most common interface on Unix platforms for handling dynamically linked libraries. It allows the program to call arbitrary functions in such a library. diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst index 99a2921..04bc219 100644 --- a/Doc/library/doctest.rst +++ b/Doc/library/doctest.rst @@ -691,12 +691,7 @@ even a single character doesn't match, the test fails. This will probably surprise you a few times, as you learn exactly what Python does and doesn't guarantee about output. For example, when printing a dict, Python doesn't guarantee that the key-value pairs will be printed in any particular order, so a -test like - -.. % Hey! What happened to Monty Python examples? -.. % Tim: ask Guido -- it's his example! - -:: +test like :: >>> foo() {"Hermione": "hippogryph", "Harry": "broomstick"} diff --git a/Doc/library/email.rst b/Doc/library/email.rst index df41563..72fb31d 100644 --- a/Doc/library/email.rst +++ b/Doc/library/email.rst @@ -1,7 +1,3 @@ -.. % Copyright (C) 2001-2007 Python Software Foundation -.. % Author: barry@python.org (Barry Warsaw) - - :mod:`email` --- An email and MIME handling package =================================================== @@ -10,6 +6,7 @@ including MIME documents. .. moduleauthor:: Barry A. Warsaw .. sectionauthor:: Barry A. Warsaw +.. Copyright (C) 2001-2007 Python Software Foundation The :mod:`email` package is a library for managing email messages, including diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst index 786e825..e7721fa 100644 --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -111,16 +111,15 @@ The following exceptions are the exceptions that are actually raised. .. exception:: AttributeError - Raised when an attribute reference or assignment fails. (When an object does - not support attribute references or attribute assignments at all, - :exc:`TypeError` is raised.) - - .. % xref to attribute reference? + Raised when an attribute reference (see :ref:`attribute-references`) or + assignment fails. (When an object does not support attribute references or + attribute assignments at all, :exc:`TypeError` is raised.) .. exception:: EOFError - Raised when attempting to read beyond the end of a file. (N.B.: the + Raised when one of the built-in functions (:func:`input` or :func:`raw_input`) + hits an end-of-file condition (EOF) without reading any data. (N.B.: the :meth:`file.read` and :meth:`file.readline` methods return an empty string when they hit EOF.) @@ -162,14 +161,14 @@ The following exceptions are the exceptions that are actually raised. truncated to fall in the allowed range; if an index is not a plain integer, :exc:`TypeError` is raised.) - .. % XXXJH xref to sequences + .. XXX xref to sequences .. exception:: KeyError Raised when a mapping (dictionary) key is not found in the set of existing keys. - .. % XXXJH xref to mapping objects? + .. XXX xref to mapping objects? .. exception:: KeyboardInterrupt diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 02c709c2..49fd77d 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -28,7 +28,7 @@ available. They are listed here in alphabetical order. :func:`__import__` function. For example, the statement ``import spam`` results in the following call: - ``__import__('spam',`` ``globals(),`` ``locals(), [], -1)``; the statement + ``__import__('spam', globals(), locals(), [], -1)``; the statement ``from spam.ham import eggs`` results in ``__import__('spam.ham', globals(), locals(), ['eggs'], -1)``. Note that even though ``locals()`` and ``['eggs']`` are passed in as arguments, the :func:`__import__` function does not set the @@ -359,7 +359,7 @@ available. They are listed here in alphabetical order. access to the standard :mod:`builtins` module and restricted environments are propagated. If the *locals* dictionary is omitted it defaults to the *globals* dictionary. If both dictionaries are omitted, the expression is executed in the - environment where :keyword:`eval` is called. The return value is the result of + environment where :func:`eval` is called. The return value is the result of the evaluated expression. Syntax errors are reported as exceptions. Example:: >>> x = 1 @@ -632,7 +632,7 @@ available. They are listed here in alphabetical order. The contents of this dictionary should not be modified; changes may not affect the values of local variables used by the interpreter. - Free variables are returned by *locals* when it is called in a function block. + Free variables are returned by :func:`locals` when it is called in a function block. Modifications of free variables may not affect the values used by the interpreter. Free variables are not returned in class blocks. diff --git a/Doc/library/gensuitemodule.rst b/Doc/library/gensuitemodule.rst index 3fc5254..dbbc3a0 100644 --- a/Doc/library/gensuitemodule.rst +++ b/Doc/library/gensuitemodule.rst @@ -6,9 +6,7 @@ :platform: Mac :synopsis: Create a stub package from an OSA dictionary .. sectionauthor:: Jack Jansen - - -.. % \moduleauthor{Jack Jansen?}{email} +.. moduleauthor:: Jack Jansen The :mod:`gensuitemodule` module creates a Python package implementing stub code for the AppleScript suites that are implemented by a specific application, diff --git a/Doc/library/getopt.rst b/Doc/library/getopt.rst index b7220a5..35d91d2 100644 --- a/Doc/library/getopt.rst +++ b/Doc/library/getopt.rst @@ -9,7 +9,7 @@ This module helps scripts to parse the command line arguments in ``sys.argv``. It supports the same conventions as the Unix :cfunc:`getopt` function (including -the special meanings of arguments of the form '``-``' and '``--``'). Long +the special meanings of arguments of the form '``-``' and '``--``'). Long options similar to those supported by GNU software may be used as well via an optional third argument. This module provides a single function and an exception: diff --git a/Doc/library/getpass.rst b/Doc/library/getpass.rst index 9a45b28..bd384b4 100644 --- a/Doc/library/getpass.rst +++ b/Doc/library/getpass.rst @@ -1,4 +1,3 @@ - :mod:`getpass` --- Portable password input ========================================== @@ -6,9 +5,7 @@ :synopsis: Portable reading of passwords and retrieval of the userid. .. moduleauthor:: Piers Lauder .. sectionauthor:: Fred L. Drake, Jr. - - -.. % Windows (& Mac?) support by Guido van Rossum. +.. Windows (& Mac?) support by Guido van Rossum. The :mod:`getpass` module provides two functions: diff --git a/Doc/library/heapq.rst b/Doc/library/heapq.rst index e3b145c..f26d29b 100644 --- a/Doc/library/heapq.rst +++ b/Doc/library/heapq.rst @@ -1,4 +1,3 @@ - :mod:`heapq` --- Heap queue algorithm ===================================== @@ -8,9 +7,6 @@ .. sectionauthor:: Guido van Rossum .. sectionauthor:: François Pinard - -.. % Theoretical explanation: - This module provides an implementation of the heap queue algorithm, also known as the priority queue algorithm. diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index 44b59e9..8209aa9 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -1,20 +1,16 @@ .. _idle: -Idle +IDLE ==== .. moduleauthor:: Guido van Rossum - -.. % \declaremodule{standard}{idle} -.. % \modulesynopsis{A Python Integrated Development Environment} - .. index:: - single: Idle + single: IDLE single: Python Editor single: Integrated Development Environment -Idle is the Python IDE built with the :mod:`Tkinter` GUI toolkit. +IDLE is the Python IDE built with the :mod:`Tkinter` GUI toolkit. IDLE has the following features: diff --git a/Doc/library/imaplib.rst b/Doc/library/imaplib.rst index dab22e0..10f3a42 100644 --- a/Doc/library/imaplib.rst +++ b/Doc/library/imaplib.rst @@ -1,4 +1,3 @@ - :mod:`imaplib` --- IMAP4 protocol client ======================================== @@ -6,6 +5,10 @@ :synopsis: IMAP4 protocol client (requires sockets). .. moduleauthor:: Piers Lauder .. sectionauthor:: Piers Lauder +.. revised by ESR, January 2000 +.. changes for IMAP4_SSL by Tino Lange , March 2002 +.. changes for IMAP4_stream by Piers Lauder , + November 2002 .. index:: @@ -13,14 +16,6 @@ pair: IMAP4_SSL; protocol pair: IMAP4_stream; protocol -.. % Based on HTML documentation by Piers Lauder -.. % ; -.. % converted by Fred L. Drake, Jr. . -.. % Revised by ESR, January 2000. -.. % Changes for IMAP4_SSL by Tino Lange , March 2002 -.. % Changes for IMAP4_stream by Piers Lauder -.. % , November 2002 - This module defines three classes, :class:`IMAP4`, :class:`IMAP4_SSL` and :class:`IMAP4_stream`, which encapsulate a connection to an IMAP4 server and implement a large subset of the IMAP4rev1 client protocol as defined in diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst index 54b52e4..21f6476 100644 --- a/Doc/library/itertools.rst +++ b/Doc/library/itertools.rst @@ -157,7 +157,7 @@ loops that truncate the stream. key = lambda x: x self.keyfunc = key self.it = iter(iterable) - self.tgtkey = self.currkey = self.currvalue = [] + self.tgtkey = self.currkey = self.currvalue = object() def __iter__(self): return self def __next__(self): @@ -350,14 +350,13 @@ loops that truncate the stream. is equivalent to:: def tee(iterable): - def gen(next, data={}, cnt=[0]): + def gen(next, data={}): for i in count(): - if i == cnt[0]: - item = data[i] = next() - cnt[0] += 1 + if i in data: + yield data.pop(i) else: - item = data.pop(i) - yield item + data[i] = next() + yield data[i] it = iter(iterable) return (gen(it.__next__), gen(it.__next__)) diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index 537ac3a..a95e2b5 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -2019,8 +2019,6 @@ Configuration Configuration functions ^^^^^^^^^^^^^^^^^^^^^^^ -.. % - The following functions configure the logging module. They are located in the :mod:`logging.config` module. Their use is optional --- you can configure the logging module using these functions or by making calls to the main API (defined @@ -2204,13 +2202,12 @@ Sections which specify formatter configuration are typified by the following. :: class=logging.Formatter The ``format`` entry is the overall format string, and the ``datefmt`` entry is -the :func:`strftime`\ -compatible date/time format string. If empty, the package -substitutes ISO8601 format date/times, which is almost equivalent to specifying -the date format string "The ISO8601 format also specifies milliseconds, which -are appended to the result of using the above format string, with a comma -separator. An example time in ISO8601 format is ``2003-01-23 00:29:50,411``. - -.. % Y-%m-%d %H:%M:%S". +the :func:`strftime`\ -compatible date/time format string. If empty, the +package substitutes ISO8601 format date/times, which is almost equivalent to +specifying the date format string ``"%Y-%m-%d %H:%M:%S"``. The ISO8601 format +also specifies milliseconds, which are appended to the result of using the above +format string, with a comma separator. An example time in ISO8601 format is +``2003-01-23 00:29:50,411``. The ``class`` entry is optional. It indicates the name of the formatter's class (as a dotted module and class name.) This option is useful for instantiating a diff --git a/Doc/library/mhlib.rst b/Doc/library/mhlib.rst index 0dd5353..f6edf28 100644 --- a/Doc/library/mhlib.rst +++ b/Doc/library/mhlib.rst @@ -1,13 +1,9 @@ - :mod:`mhlib` --- Access to MH mailboxes ======================================= .. module:: mhlib :synopsis: Manipulate MH mailboxes from Python. - - -.. % LaTeX'ized from the comments in the module by Skip Montanaro -.. % . +.. sectionauthor:: Skip Montanaro The :mod:`mhlib` module provides a Python interface to MH folders and their contents. diff --git a/Doc/library/nntplib.rst b/Doc/library/nntplib.rst index c3de3d7..761190d 100644 --- a/Doc/library/nntplib.rst +++ b/Doc/library/nntplib.rst @@ -309,8 +309,6 @@ indicates an error, the method raises one of the above exceptions. is supplied, then the returned *list* is an empty list. This is an optional NNTP extension, and may not be supported by all servers. - .. % XXX huh? Should that be (name, description)? - RFC2980 says "It is suggested that this extension be deprecated". Use :meth:`descriptions` or :meth:`description` instead. diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst index f5488e7..e6668b6 100644 --- a/Doc/library/optparse.rst +++ b/Doc/library/optparse.rst @@ -1,7 +1,3 @@ -.. % THIS FILE IS AUTO-GENERATED! DO NOT EDIT! -.. % (Your changes will be lost the next time it is generated.) - - :mod:`optparse` --- More powerful command line option parser ============================================================ @@ -18,9 +14,6 @@ populate it with options, and parse the command line. ``optparse`` allows users to specify options in the conventional GNU/POSIX syntax, and additionally generates usage and help messages for you. -.. % An intro blurb used only when generating LaTeX docs for the Python -.. % manual (based on README.txt). - Here's an example of using ``optparse`` in a simple script:: from optparse import OptionParser @@ -70,8 +63,6 @@ and ``optparse`` will print out a brief summary of your script's options:: where the value of *yourscript* is determined at runtime (normally from ``sys.argv[0]``). -.. % $Id: intro.txt 413 2004-09-28 00:59:13Z greg $ - .. _optparse-background: @@ -233,8 +224,6 @@ you implement, the more flexible your program is, and the more complicated its implementation becomes. Too much flexibility has drawbacks as well, of course; too many options can overwhelm users and make your code much harder to maintain. -.. % $Id: tao.txt 413 2004-09-28 00:59:13Z greg $ - .. _optparse-tutorial: @@ -652,8 +641,6 @@ Here's what :mod:`optparse`\ -based scripts usually look like:: if __name__ == "__main__": main() -.. % $Id: tutorial.txt 515 2006-06-10 15:37:45Z gward $ - .. _optparse-reference-guide: @@ -1329,8 +1316,6 @@ OptionParser supports several other public methods: parser.add_option("--novice", action="store_const", dest="mode", const="novice") -.. % $Id: reference.txt 519 2006-06-11 14:39:11Z gward $ - .. _optparse-option-callbacks: @@ -1626,8 +1611,6 @@ in the arguments following ``"-c"`` will be interpreted as further options (probably causing an error), rather than as arguments to ``"-c"``. Fixing this is left as an exercise for the reader. -.. % $Id: callbacks.txt 415 2004-09-30 02:26:17Z greg $ - .. _optparse-extending-optparse: @@ -1818,6 +1801,3 @@ Features of note: about setting a default value for the option destinations in question; they can just leave the default as None and :meth:`ensure_value` will take care of getting it right when it's needed. - -.. % $Id: extending.txt 517 2006-06-10 16:18:11Z gward $ - diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 2a8325a..71e5f36 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -291,9 +291,8 @@ process and user. Set the current process' user id. Availability: Unix. -.. % placed in this section since it relates to errno.... a little weak - +.. placed in this section since it relates to errno.... a little weak .. function:: strerror(code) Return the error message corresponding to the error code in *code*. diff --git a/Doc/library/ossaudiodev.rst b/Doc/library/ossaudiodev.rst index 7be838b..e23b049 100644 --- a/Doc/library/ossaudiodev.rst +++ b/Doc/library/ossaudiodev.rst @@ -11,33 +11,33 @@ This module allows you to access the OSS (Open Sound System) audio interface. OSS is available for a wide range of open-source and commercial Unices, and is the standard audio interface for Linux and recent versions of FreeBSD. -.. % Things will get more complicated for future Linux versions, since -.. % ALSA is in the standard kernel as of 2.5.x. Presumably if you -.. % use ALSA, you'll have to make sure its OSS compatibility layer -.. % is active to use ossaudiodev, but you're gonna need it for the vast -.. % majority of Linux audio apps anyways. -.. % -.. % Sounds like things are also complicated for other BSDs. In response -.. % to my python-dev query, Thomas Wouters said: -.. % -.. % > Likewise, googling shows OpenBSD also uses OSS/Free -- the commercial -.. % > OSS installation manual tells you to remove references to OSS/Free from the -.. % > kernel :) -.. % -.. % but Aleksander Piotrowsk actually has an OpenBSD box, and he quotes -.. % from its : -.. % > * WARNING! WARNING! -.. % > * This is an OSS (Linux) audio emulator. -.. % > * Use the Native NetBSD API for developing new code, and this -.. % > * only for compiling Linux programs. -.. % -.. % There's also an ossaudio manpage on OpenBSD that explains things -.. % further. Presumably NetBSD and OpenBSD have a different standard -.. % audio interface. That's the great thing about standards, there are so -.. % many to choose from ... ;-) -.. % -.. % This probably all warrants a footnote or two, but I don't understand -.. % things well enough right now to write it! --GPW +.. Things will get more complicated for future Linux versions, since + ALSA is in the standard kernel as of 2.5.x. Presumably if you + use ALSA, you'll have to make sure its OSS compatibility layer + is active to use ossaudiodev, but you're gonna need it for the vast + majority of Linux audio apps anyways. + + Sounds like things are also complicated for other BSDs. In response + to my python-dev query, Thomas Wouters said: + + > Likewise, googling shows OpenBSD also uses OSS/Free -- the commercial + > OSS installation manual tells you to remove references to OSS/Free from the + > kernel :) + + but Aleksander Piotrowsk actually has an OpenBSD box, and he quotes + from its : + > * WARNING! WARNING! + > * This is an OSS (Linux) audio emulator. + > * Use the Native NetBSD API for developing new code, and this + > * only for compiling Linux programs. + + There's also an ossaudio manpage on OpenBSD that explains things + further. Presumably NetBSD and OpenBSD have a different standard + audio interface. That's the great thing about standards, there are so + many to choose from ... ;-) + + This probably all warrants a footnote or two, but I don't understand + things well enough right now to write it! --GPW .. seealso:: @@ -87,6 +87,10 @@ the standard audio interface for Linux and recent versions of FreeBSD. second is required. This is a historical artifact for compatibility with the older :mod:`linuxaudiodev` module which :mod:`ossaudiodev` supersedes. + .. XXX it might also be motivated + by my unfounded-but-still-possibly-true belief that the default + audio device varies unpredictably across operating systems. -GW + .. function:: openmixer([device]) diff --git a/Doc/library/othergui.rst b/Doc/library/othergui.rst index 5a84285..b36568d 100644 --- a/Doc/library/othergui.rst +++ b/Doc/library/othergui.rst @@ -5,7 +5,6 @@ Other Graphical User Interface Packages There are an number of extension widget sets to :mod:`Tkinter`. - .. seealso:: `Python megawidgets `_ @@ -29,12 +28,10 @@ There are an number of extension widget sets to :mod:`Tkinter`. since they can operate directly on Python data structures, without having to transfer data through the Tk/Tcl layer. - .. % The major cross-platform (Windows, Mac OS X, Unix-like) GUI toolkits that are also available for Python: - .. seealso:: `PyGTK `_ diff --git a/Doc/library/parser.rst b/Doc/library/parser.rst index 9323090..b0e509a 100644 --- a/Doc/library/parser.rst +++ b/Doc/library/parser.rst @@ -8,13 +8,12 @@ .. sectionauthor:: Fred L. Drake, Jr. -.. % Copyright 1995 Virginia Polytechnic Institute and State University -.. % and Fred L. Drake, Jr. This copyright notice must be distributed on -.. % all copies, but this document otherwise may be distributed as part -.. % of the Python distribution. No fee may be charged for this document -.. % in any representation, either on paper or electronically. This -.. % restriction does not affect other elements in a distributed package -.. % in any way. +.. Copyright 1995 Virginia Polytechnic Institute and State University and Fred + L. Drake, Jr. This copyright notice must be distributed on all copies, but + this document otherwise may be distributed as part of the Python + distribution. No fee may be charged for this document in any representation, + either on paper or electronically. This restriction does not affect other + elements in a distributed package in any way. .. index:: single: parsing; Python source code diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst index c88fc29..7e04f5b 100644 --- a/Doc/library/pickle.rst +++ b/Doc/library/pickle.rst @@ -1,4 +1,3 @@ - :mod:`pickle` --- Python object serialization ============================================= @@ -12,10 +11,8 @@ .. module:: pickle :synopsis: Convert Python objects to streams of bytes and back. - - -.. % Substantial improvements by Jim Kerr . -.. % Rewritten by Barry Warsaw +.. sectionauthor:: Jim Kerr . +.. sectionauthor:: Barry Warsaw The :mod:`pickle` module implements a fundamental, but powerful algorithm for serializing and de-serializing a Python object structure. "Pickling" is the @@ -607,10 +604,10 @@ object references without actually instantiating all the objects in a pickle. [#]_ Setting :attr:`persistent_load` to a list is usually used in conjunction with the :meth:`noload` method on the Unpickler. -.. % BAW: Both pickle and cPickle support something called -.. % inst_persistent_id() which appears to give unknown types a second -.. % shot at producing a persistent id. Since Jim Fulton can't remember -.. % why it was added or what it's for, I'm leaving it undocumented. +.. BAW: Both pickle and cPickle support something called inst_persistent_id() + which appears to give unknown types a second shot at producing a persistent + id. Since Jim Fulton can't remember why it was added or what it's for, I'm + leaving it undocumented. .. _pickle-sub: diff --git a/Doc/library/platform.rst b/Doc/library/platform.rst index a668075..cddaa58 100644 --- a/Doc/library/platform.rst +++ b/Doc/library/platform.rst @@ -194,16 +194,12 @@ Windows Platform Win95/98 specific ^^^^^^^^^^^^^^^^^ - .. function:: popen(cmd, mode='r', bufsize=None) Portable :func:`popen` interface. Find a working popen implementation preferring :func:`win32pipe.popen`. On Windows NT, :func:`win32pipe.popen` should work; on Windows 9x it hangs due to bugs in the MS C library. - .. % This KnowledgeBase article appears to be missing... - .. % See also \ulink{MS KnowledgeBase article Q150956}{}. - Mac OS Platform --------------- @@ -231,7 +227,7 @@ Unix Platforms Tries to determine the name of the OS distribution name Returns a tuple ``(distname, version, id)`` which defaults to the args given as parameters. -.. % Document linux_distribution()? +.. XXX Document linux_distribution()? .. function:: libc_ver(executable=sys.executable, lib='', version='', chunksize=2048) diff --git a/Doc/library/poplib.rst b/Doc/library/poplib.rst index b462ec5..893296f 100644 --- a/Doc/library/poplib.rst +++ b/Doc/library/poplib.rst @@ -4,16 +4,11 @@ .. module:: poplib :synopsis: POP3 protocol client (requires sockets). - +.. sectionauthor:: Andrew T. Csillag +.. revised by ESR, January 2000 .. index:: pair: POP3; protocol -.. % By Andrew T. Csillag -.. % Even though I put it into LaTeX, I cannot really claim that I wrote -.. % it since I just stole most of it from the poplib.py source code and -.. % the imaplib ``chapter''. -.. % Revised by ESR, January 2000 - This module defines a class, :class:`POP3`, which encapsulates a connection to a POP3 server and implements the protocol as defined in :rfc:`1725`. The :class:`POP3` class supports both the minimal and optional command sets. diff --git a/Doc/library/pprint.rst b/Doc/library/pprint.rst index 2e4f3f2..22407ed 100644 --- a/Doc/library/pprint.rst +++ b/Doc/library/pprint.rst @@ -24,7 +24,7 @@ Dictionaries are sorted by key before the display is computed. The :mod:`pprint` module defines one class: -.. % First the implementation class: +.. First the implementation class: .. class:: PrettyPrinter(...) @@ -65,8 +65,7 @@ The :mod:`pprint` module defines one class: The :class:`PrettyPrinter` class supports several derivative functions: -.. % Now the derivative functions: - +.. Now the derivative functions: .. function:: pformat(object[, indent[, width[, depth]]]) @@ -123,9 +122,6 @@ One more support function is also defined: recursive reference will be represented as ````. The representation is not otherwise formatted. -.. % This example is outside the {funcdesc} to keep it from running over -.. % the right margin. - :: >>> pprint.saferepr(stuff) diff --git a/Doc/library/profile.rst b/Doc/library/profile.rst index cc02436..fe3cadf 100644 --- a/Doc/library/profile.rst +++ b/Doc/library/profile.rst @@ -72,47 +72,47 @@ is not so far as well-tested and might not be available on all systems. :mod:`cProfile` is really a compatibility layer on top of the internal :mod:`_lsprof` module. -.. % \section{How Is This Profiler Different From The Old Profiler?} -.. % \nodename{Profiler Changes} -.. % -.. % (This section is of historical importance only; the old profiler -.. % discussed here was last seen in Python 1.1.) -.. % -.. % The big changes from old profiling module are that you get more -.. % information, and you pay less CPU time. It's not a trade-off, it's a -.. % trade-up. -.. % -.. % To be specific: -.. % -.. % \begin{description} -.. % -.. % \item[Bugs removed:] -.. % Local stack frame is no longer molested, execution time is now charged -.. % to correct functions. -.. % -.. % \item[Accuracy increased:] -.. % Profiler execution time is no longer charged to user's code, -.. % calibration for platform is supported, file reads are not done \emph{by} -.. % profiler \emph{during} profiling (and charged to user's code!). -.. % -.. % \item[Speed increased:] -.. % Overhead CPU cost was reduced by more than a factor of two (perhaps a -.. % factor of five), lightweight profiler module is all that must be -.. % loaded, and the report generating module (\module{pstats}) is not needed -.. % during profiling. -.. % -.. % \item[Recursive functions support:] -.. % Cumulative times in recursive functions are correctly calculated; -.. % recursive entries are counted. -.. % -.. % \item[Large growth in report generating UI:] -.. % Distinct profiles runs can be added together forming a comprehensive -.. % report; functions that import statistics take arbitrary lists of -.. % files; sorting criteria is now based on keywords (instead of 4 integer -.. % options); reports shows what functions were profiled as well as what -.. % profile file was referenced; output format has been improved. -.. % -.. % \end{description} +.. \section{How Is This Profiler Different From The Old Profiler?} + \nodename{Profiler Changes} + + (This section is of historical importance only; the old profiler + discussed here was last seen in Python 1.1.) + + The big changes from old profiling module are that you get more + information, and you pay less CPU time. It's not a trade-off, it's a + trade-up. + + To be specific: + + \begin{description} + + \item[Bugs removed:] + Local stack frame is no longer molested, execution time is now charged + to correct functions. + + \item[Accuracy increased:] + Profiler execution time is no longer charged to user's code, + calibration for platform is supported, file reads are not done \emph{by} + profiler \emph{during} profiling (and charged to user's code!). + + \item[Speed increased:] + Overhead CPU cost was reduced by more than a factor of two (perhaps a + factor of five), lightweight profiler module is all that must be + loaded, and the report generating module (\module{pstats}) is not needed + during profiling. + + \item[Recursive functions support:] + Cumulative times in recursive functions are correctly calculated; + recursive entries are counted. + + \item[Large growth in report generating UI:] + Distinct profiles runs can be added together forming a comprehensive + report; functions that import statistics take arbitrary lists of + files; sorting criteria is now based on keywords (instead of 4 integer + options); reports shows what functions were profiled as well as what + profile file was referenced; output format has been improved. + + \end{description} .. _profile-instant: @@ -172,7 +172,7 @@ second method sorted all the entries according to the standard module/line/name string that is printed. The third method printed out all the statistics. You might try the following sort calls: -.. % (this is to comply with the semantics of the old profiler). +.. (this is to comply with the semantics of the old profiler). :: @@ -363,6 +363,8 @@ Analysis of the profiler data is done using the :class:`Stats` class. a single report. If additional files need to be combined with data in an existing :class:`Stats` object, the :meth:`add` method can be used. + .. (such as the old system profiler). + .. _profile-stats: @@ -457,7 +459,7 @@ The :class:`Stats` Class (numeric) is used, only one sort key (the numeric key) will be used, and additional arguments will be silently ignored. - .. % For compatibility with the old profiler, + .. For compatibility with the old profiler, .. method:: Stats.reverse_order() @@ -466,8 +468,7 @@ The :class:`Stats` Class within the object. Note that by default ascending vs descending order is properly selected based on the sort key of choice. - .. % This method is provided primarily for - .. % compatibility with the old profiler. + .. This method is provided primarily for compatibility with the old profiler. .. method:: Stats.print_stats([restriction, ...]) diff --git a/Doc/library/py_compile.rst b/Doc/library/py_compile.rst index c815846..de9a80e 100644 --- a/Doc/library/py_compile.rst +++ b/Doc/library/py_compile.rst @@ -3,11 +3,8 @@ .. module:: py_compile :synopsis: Generate byte-code files from Python source files. - -.. % Documentation based on module docstrings, by Fred L. Drake, Jr. -.. % - - +.. sectionauthor:: Fred L. Drake, Jr. +.. documentation based on module docstrings .. index:: pair: file; byte-code diff --git a/Doc/library/pyclbr.rst b/Doc/library/pyclbr.rst index a052a69..788c60c 100644 --- a/Doc/library/pyclbr.rst +++ b/Doc/library/pyclbr.rst @@ -24,7 +24,7 @@ in Python, including many standard and optional extension modules. be a sequence, and is used to augment the value of ``sys.path``, which is used to locate module source code. - .. % The 'inpackage' parameter appears to be for internal use only.... + .. The 'inpackage' parameter appears to be for internal use only.... .. function:: readmodule_ex(module[, path]) @@ -35,7 +35,7 @@ in Python, including many standard and optional extension modules. the key ``'__path__'`` in the returned dictionary has as its value a list which contains the package search path. - .. % The 'inpackage' parameter appears to be for internal use only.... + .. The 'inpackage' parameter appears to be for internal use only.... .. _pyclbr-class-objects: diff --git a/Doc/library/pyexpat.rst b/Doc/library/pyexpat.rst index fcb7705..29ca540 100644 --- a/Doc/library/pyexpat.rst +++ b/Doc/library/pyexpat.rst @@ -7,14 +7,13 @@ .. moduleauthor:: Paul Prescod -.. % Markup notes: -.. % -.. % Many of the attributes of the XMLParser objects are callbacks. -.. % Since signature information must be presented, these are described -.. % using the methoddesc environment. Since they are attributes which -.. % are set by client code, in-text references to these attributes -.. % should be marked using the \member macro and should not include the -.. % parentheses used when marking functions and methods. +.. Markup notes: + + Many of the attributes of the XMLParser objects are callbacks. Since + signature information must be presented, these are described using the method + directive. Since they are attributes which are set by client code, in-text + references to these attributes should be marked using the :member: role. + .. index:: single: Expat diff --git a/Doc/library/re.rst b/Doc/library/re.rst index 88912eb..49c5215 100644 --- a/Doc/library/re.rst +++ b/Doc/library/re.rst @@ -84,8 +84,6 @@ the null byte using the ``\number`` notation, e.g., ``'\x00'``. The special characters are: -.. % - ``'.'`` (Dot.) In the default mode, this matches any character except a newline. If the :const:`DOTALL` flag has been specified, this matches any character @@ -297,8 +295,6 @@ The special sequences consist of ``'\'`` and a character from the list below. If the ordinary character is not on the list, then the resulting RE will match the second character. For example, ``\$`` matches the character ``'$'``. -.. % - ``\number`` Matches the contents of the group of the same number. Groups are numbered starting from 1. For example, ``(.+) \1`` matches ``'the the'`` or ``'55 55'``, @@ -384,9 +380,6 @@ there are three octal digits, it is considered an octal escape. Otherwise, it is a group reference. As for string literals, octal escapes are always at most three digits in length. -.. % Note the lack of a period in the section title; it causes problems -.. % with readers of the GNU info version. See http://www.python.org/sf/581414. - .. _matching-searching: @@ -406,15 +399,11 @@ beginning with ``'^'``: ``'^'`` matches only at the start of the string, or in :const:`MULTILINE` mode also immediately following a newline. The "match" operation succeeds only if the pattern matches at the start of the string regardless of mode, or at the starting position given by the optional *pos* -argument regardless of whether a newline precedes it. - -.. % Examples from Tim Peters: - -:: +argument regardless of whether a newline precedes it. :: >>> re.match("c", "abcdef") # No match >>> re.search("c", "abcdef") - <_sre.SRE_Match object at 0x827e9c0> # Match + <_sre.SRE_Match object at 0x827e9c0> # Match .. _contents-of-module-re: @@ -450,10 +439,9 @@ form. but the version using :func:`compile` is more efficient when the expression will be used several times in a single program. - .. % (The compiled version of the last pattern passed to - .. % \function{re.match()} or \function{re.search()} is cached, so - .. % programs that use only a single regular expression at a time needn't - .. % worry about compiling regular expressions.) + .. (The compiled version of the last pattern passed to :func:`re.match` or + :func:`re.search` is cached, so programs that use only a single regular + expression at a time needn't worry about compiling regular expressions.) .. data:: I diff --git a/Doc/library/sched.rst b/Doc/library/sched.rst index c262a8d..57f9b5c 100644 --- a/Doc/library/sched.rst +++ b/Doc/library/sched.rst @@ -1,4 +1,3 @@ - :mod:`sched` --- Event scheduler ================================ @@ -6,9 +5,6 @@ :synopsis: General purpose event scheduler. .. sectionauthor:: Moshe Zadka - -.. % LaTeXed and enhanced from comments in file - .. index:: single: event scheduling The :mod:`sched` module defines a class which implements a general purpose event diff --git a/Doc/library/select.rst b/Doc/library/select.rst index f68a0da..4a97179 100644 --- a/Doc/library/select.rst +++ b/Doc/library/select.rst @@ -58,8 +58,6 @@ The module defines the following: class yourself, as long as it has an appropriate :meth:`fileno` method (that really returns a file descriptor, not just a random integer). - .. % - .. note:: .. index:: single: WinSock diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index 3fdaa1f..3275179 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -5,9 +5,7 @@ .. module:: shutil :synopsis: High-level file operations, including copying. .. sectionauthor:: Fred L. Drake, Jr. - - -.. % partly based on the docstrings +.. partly based on the docstrings .. index:: single: file; copying diff --git a/Doc/library/sndhdr.rst b/Doc/library/sndhdr.rst index 90d71a9..01a3917 100644 --- a/Doc/library/sndhdr.rst +++ b/Doc/library/sndhdr.rst @@ -5,9 +5,7 @@ .. module:: sndhdr :synopsis: Determine type of a sound file. .. sectionauthor:: Fred L. Drake, Jr. - - -.. % Based on comments in the module source file. +.. Based on comments in the module source file. .. index:: single: A-LAW diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index 5c3d9f6..a6557e1 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -542,7 +542,7 @@ correspond to Unix system calls applicable to sockets. file object and socket object may be closed or garbage-collected independently. The socket must be in blocking mode (it can not have a timeout). The optional *mode* and *bufsize* arguments are interpreted the same way as by the built-in - :func:`file` function; see :ref:`built-in-funcs` for more information. + :func:`file` function. .. method:: socket.recv(bufsize[, flags]) diff --git a/Doc/library/socketserver.rst b/Doc/library/socketserver.rst index 96fae6b..c900ea7 100644 --- a/Doc/library/socketserver.rst +++ b/Doc/library/socketserver.rst @@ -115,9 +115,8 @@ next (or whether to handle a new incoming request). This is particularly important for stream services where each client can potentially be connected for a long time (if threads or subprocesses cannot be used). -.. % XXX should data and methods be intermingled, or separate? -.. % how should the distinction between class and instance variables be -.. % drawn? +.. XXX should data and methods be intermingled, or separate? + how should the distinction between class and instance variables be drawn? Server Objects @@ -171,8 +170,7 @@ Server Objects The server classes support the following class variables: -.. % XXX should class variables be covered before instance variables, or -.. % vice versa? +.. XXX should class variables be covered before instance variables, or vice versa? .. data:: allow_reuse_address @@ -199,8 +197,8 @@ There are various server methods that can be overridden by subclasses of base server classes like :class:`TCPServer`; these methods aren't useful to external users of the server object. -.. % should the default implementations of these be documented, or should -.. % it be assumed that the user will look at SocketServer.py? +.. XXX should the default implementations of these be documented, or should + it be assumed that the user will look at SocketServer.py? .. function:: finish_request() @@ -230,9 +228,9 @@ users of the server object. or thread to handle the request; the :class:`ForkingMixIn` and :class:`ThreadingMixIn` classes do this. -.. % Is there any point in documenting the following two functions? -.. % What would the purpose of overriding them be: initializing server -.. % instance variables, adding new network families? +.. Is there any point in documenting the following two functions? + What would the purpose of overriding them be: initializing server + instance variables, adding new network families? .. function:: server_activate() diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 0b569bf..9d12d34 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -349,7 +349,7 @@ A :class:`Connection` instance has the following attributes and methods: memory overhead. It will probably be better than your own custom dictionary-based approach or even a db_row based solution. - .. % XXX what's a db_row-based solution? + .. XXX what's a db_row-based solution? .. attribute:: Connection.text_factory diff --git a/Doc/library/statvfs.rst b/Doc/library/statvfs.rst index 6ec7c38..0b32f65 100644 --- a/Doc/library/statvfs.rst +++ b/Doc/library/statvfs.rst @@ -1,4 +1,3 @@ - :mod:`statvfs` --- Constants used with :func:`os.statvfs` ========================================================= @@ -7,8 +6,6 @@ .. sectionauthor:: Moshe Zadka -.. % LaTeX'ed from comments in module - The :mod:`statvfs` module defines constants so interpreting the result if :func:`os.statvfs`, which returns a tuple, can be made without remembering "magic numbers." Each of the constants defined in this module is the *index* of diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 196ad49..9763cba 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -162,6 +162,24 @@ This table summarizes the comparison operations: +------------+-------------------------+-------+ .. index:: + pair: operator; comparison + operator: == + operator: < + operator: <= + operator: > + operator: >= + operator: != + operator: is + operator: is not + +Notes: + +(1) + ``!=`` can also be written ``<>``, but this is an obsolete usage + kept for backwards compatibility only. New code should always use + ``!=``. + +.. index:: pair: object; numeric pair: objects; comparing @@ -335,8 +353,8 @@ Notes: .. versionadded:: 2.6 - -.. % XXXJH exceptions: overflow (when? what operations?) zerodivision + +.. XXXJH exceptions: overflow (when? what operations?) zerodivision .. _bitstring-ops: @@ -1154,6 +1172,8 @@ Notes: Since Python strings have an explicit length, ``%s`` conversions do not assume that ``'\0'`` is the end of the string. +.. XXX Examples? + For safety reasons, floating point precisions are clipped to 50; ``%f`` conversions for numbers whose absolute value is over 1e25 are replaced by ``%g`` conversions. [#]_ All other errors raise exceptions. @@ -1845,8 +1865,7 @@ File Objects .. XXX this is quite out of date, must be updated with "io" module File objects are implemented using C's ``stdio`` package and can be -created with the built-in :func:`file` and (more usually) :func:`open` -constructors described in the :ref:`built-in-funcs` section. [#]_ File +created with the built-in :func:`open` function. File objects are also returned by some other built-in functions and methods, such as :func:`os.popen` and :func:`os.fdopen` and the :meth:`makefile` method of socket o