Python-checkins

Download

python-checkins@python.org

August 2007

7 participants
791 discussions

r56675 - peps/trunk/pep-3141.txt
by guido.van.rossum Aug. 2, 2007

Aug. 2, 2007

Author: guido.van.rossum Date: Thu Aug 2 21:43:38 2007 New Revision: 56675 Modified: peps/trunk/pep-3141.txt Log: New ersion by Jeffrey, nearing perfection. :-) Modified: peps/trunk/pep-3141.txt ============================================================================== --- peps/trunk/pep-3141.txt (original) +++ peps/trunk/pep-3141.txt Thu Aug 2 21:43:38 2007 @@ -7,7 +7,7 @@ Type: Standards Track Content-Type: text/x-rst Created: 23-Apr-2007 -Post-History: 25-Apr-2007, 16-May-2007, xx-Aug-2007 +Post-History: 25-Apr-2007, 16-May-2007, 02-Aug-2007 Abstract @@ -39,6 +39,9 @@ terminology from PEP 3119, but the hierarchy is intended to be meaningful for any systematic method of defining sets of classes. +The type checks in the standard library should use these classes +instead of the concrete built-ins. + Numeric Classes --------------- @@ -52,7 +55,9 @@ Most implementations of complex numbers will be hashable, but if you need to rely on that, you'll have to check it explicitly: mutable -numbers are supported by this hierarchy. :: +numbers are supported by this hierarchy. **Open issue:** Should +__pos__ coerce the argument to be an instance of the type it's defined +on? Why do the builtins do this? :: class Complex(Number): """Complex defines the operations that work on the builtin complex type. @@ -199,7 +204,7 @@ @abstractmethod def __floordiv__(self, other): - """The floor() of self/other.""" + """The floor() of self/other. Integral.""" raise NotImplementedError @abstractmethod @@ -220,6 +225,7 @@ """< on Reals defines a total ordering, except perhaps for NaN.""" raise NotImplementedError + @abstractmethod def __le__(self, other): raise NotImplementedError @@ -380,19 +386,20 @@ least Integral ``>= x``. 4. ``__round__(self)``, called from ``round(x)``, with returns the - Integral closest to ``x``, rounding half toward even. We could - support the 2-argument version, but then we'd only return an - Integral if the second argument were ``<= 0``. + Integral closest to ``x``, rounding half toward even. **Open + issue:** We could support the 2-argument version, but then we'd + only return an Integral if the second argument were ``<= 0``. 5. ``__properfraction__(self)``, called from a new function, ``math.properfraction(x)``, which resembles C's ``modf()``: returns a pair ``(n:Integral, r:Real)`` where ``x == n + r``, both ``n`` and ``r`` have the same sign as ``x``, and ``abs(r) < 1``. **Open - issue:** Oh, we already have ``math.modf``. Do we want to keep the - bad name? + issue:** Oh, we already have ``math.modf``. What name do we want + for this? Should we use divmod(x, 1) instead? Because the ``int()`` conversion from ``float`` is equivalent to but -less explicit than ``trunc()``, let's remove it. +less explicit than ``trunc()``, let's remove it. (Or, if that breaks +too much, just add a deprecation warning.) ``complex.__{divmod,mod,floordiv,int,float}__`` should also go away. These should continue to raise ``TypeError`` to help confused

1 0

r56674 - in doctools/trunk: Doc-26/TODO Doc-26/about.rst Doc-26/c-api/concrete.rst Doc-26/c-api/intro.rst Doc-26/c-api/newtypes.rst Doc-26/c-api/utilities.rst Doc-26/distutils/index.rst Doc-26/distutils/introduction.rst Doc-26/extending/building.rst Doc-26/extending/extending.rst Doc-26/extending/newtypes.rst Doc-26/extending/windows.rst Doc-26/install/index.rst Doc-26/library/array.rst Doc-26/library/ast.rst Doc-26/library/audioop.rst Doc-26/library/codecs.rst Doc-26/library/distutils.rst
by georg.brandl Aug. 2, 2007

Aug. 2, 2007

Author: georg.brandl Date: Thu Aug 2 20:07:46 2007 New Revision: 56674 Modified: doctools/trunk/Doc-26/TODO doctools/trunk/Doc-26/about.rst doctools/trunk/Doc-26/c-api/concrete.rst doctools/trunk/Doc-26/c-api/intro.rst doctools/trunk/Doc-26/c-api/newtypes.rst doctools/trunk/Doc-26/c-api/utilities.rst doctools/trunk/Doc-26/distutils/index.rst doctools/trunk/Doc-26/distutils/introduction.rst doctools/trunk/Doc-26/extending/building.rst doctools/trunk/Doc-26/extending/extending.rst doctools/trunk/Doc-26/extending/newtypes.rst doctools/trunk/Doc-26/extending/windows.rst doctools/trunk/Doc-26/install/index.rst doctools/trunk/Doc-26/library/array.rst doctools/trunk/Doc-26/library/ast.rst doctools/trunk/Doc-26/library/audioop.rst doctools/trunk/Doc-26/library/codecs.rst doctools/trunk/Doc-26/library/distutils.rst doctools/trunk/Doc-26/library/exceptions.rst doctools/trunk/Doc-26/library/functions.rst doctools/trunk/Doc-26/library/objects.rst doctools/trunk/Doc-26/library/operator.rst doctools/trunk/Doc-26/library/parser.rst doctools/trunk/Doc-26/library/pdb.rst doctools/trunk/Doc-26/library/stdtypes.rst doctools/trunk/Doc-26/library/warnings.rst doctools/trunk/Doc-26/library/weakref.rst doctools/trunk/Doc-26/library/webbrowser.rst doctools/trunk/Doc-26/library/xml.etree.elementtree.rst doctools/trunk/Doc-26/library/xml.sax.handler.rst doctools/trunk/Doc-26/maclib/mac.rst doctools/trunk/Doc-26/reference/datamodel.rst doctools/trunk/Doc-26/reference/expressions.rst doctools/trunk/Doc-26/reference/introduction.rst doctools/trunk/Doc-26/reference/lexical_analysis.rst doctools/trunk/Doc-26/reference/simple_stmts.rst doctools/trunk/Doc-26/tutorial/controlflow.rst doctools/trunk/Doc-26/tutorial/datastructures.rst doctools/trunk/Doc-26/tutorial/errors.rst doctools/trunk/Doc-26/tutorial/glossary.rst doctools/trunk/Doc-26/tutorial/inputoutput.rst doctools/trunk/Doc-26/tutorial/interactive.rst doctools/trunk/Doc-26/tutorial/interpreter.rst doctools/trunk/Doc-26/tutorial/modules.rst doctools/trunk/Doc-26/tutorial/stdlib.rst doctools/trunk/Doc-26/tutorial/stdlib2.rst doctools/trunk/Doc-26/tutorial/whatnow.rst doctools/trunk/Doc-26/whatsnew/2.3.rst doctools/trunk/Doc-26/whatsnew/2.4.rst doctools/trunk/Doc-26/whatsnew/2.6.rst doctools/trunk/Doc-3k/TODO doctools/trunk/Doc-3k/about.rst doctools/trunk/Doc-3k/c-api/concrete.rst doctools/trunk/Doc-3k/c-api/intro.rst doctools/trunk/Doc-3k/c-api/newtypes.rst doctools/trunk/Doc-3k/c-api/utilities.rst doctools/trunk/Doc-3k/distutils/index.rst doctools/trunk/Doc-3k/distutils/introduction.rst doctools/trunk/Doc-3k/extending/building.rst doctools/trunk/Doc-3k/extending/extending.rst doctools/trunk/Doc-3k/extending/newtypes.rst doctools/trunk/Doc-3k/extending/windows.rst doctools/trunk/Doc-3k/install/index.rst doctools/trunk/Doc-3k/library/array.rst doctools/trunk/Doc-3k/library/audioop.rst doctools/trunk/Doc-3k/library/codecs.rst doctools/trunk/Doc-3k/library/distutils.rst doctools/trunk/Doc-3k/library/exceptions.rst doctools/trunk/Doc-3k/library/functions.rst doctools/trunk/Doc-3k/library/objects.rst doctools/trunk/Doc-3k/library/operator.rst doctools/trunk/Doc-3k/library/parser.rst doctools/trunk/Doc-3k/library/pdb.rst doctools/trunk/Doc-3k/library/stdtypes.rst doctools/trunk/Doc-3k/library/warnings.rst doctools/trunk/Doc-3k/library/weakref.rst doctools/trunk/Doc-3k/library/webbrowser.rst doctools/trunk/Doc-3k/library/xml.etree.elementtree.rst doctools/trunk/Doc-3k/library/xml.sax.handler.rst doctools/trunk/Doc-3k/maclib/mac.rst doctools/trunk/Doc-3k/reference/datamodel.rst doctools/trunk/Doc-3k/reference/expressions.rst doctools/trunk/Doc-3k/reference/introduction.rst doctools/trunk/Doc-3k/reference/lexical_analysis.rst doctools/trunk/Doc-3k/reference/simple_stmts.rst doctools/trunk/Doc-3k/tutorial/controlflow.rst doctools/trunk/Doc-3k/tutorial/datastructures.rst doctools/trunk/Doc-3k/tutorial/errors.rst doctools/trunk/Doc-3k/tutorial/glossary.rst doctools/trunk/Doc-3k/tutorial/inputoutput.rst doctools/trunk/Doc-3k/tutorial/interactive.rst doctools/trunk/Doc-3k/tutorial/interpreter.rst doctools/trunk/Doc-3k/tutorial/modules.rst doctools/trunk/Doc-3k/tutorial/stdlib.rst doctools/trunk/Doc-3k/tutorial/stdlib2.rst doctools/trunk/Doc-3k/tutorial/whatnow.rst doctools/trunk/Doc-3k/whatsnew/2.3.rst doctools/trunk/Doc-3k/whatsnew/2.4.rst doctools/trunk/Doc-3k/whatsnew/2.6.rst Log: Replace all previously inter-document links by :ref:s. Modified: doctools/trunk/Doc-26/TODO ============================================================================== --- doctools/trunk/Doc-26/TODO (original) +++ doctools/trunk/Doc-26/TODO Thu Aug 2 20:07:46 2007 @@ -1,7 +1,6 @@ To do after conversion ====================== -* fix all references and links marked with `XXX` * split very large files and add toctrees * integrate standalone HOWTOs * find out which files get "comments disabled" metadata Modified: doctools/trunk/Doc-26/about.rst ============================================================================== --- doctools/trunk/Doc-26/about.rst (original) +++ doctools/trunk/Doc-26/about.rst Thu Aug 2 20:07:46 2007 @@ -2,6 +2,7 @@ About these documents ===================== + These documents are generated from `reStructuredText <http://docutils.sf.net/rst.html>`_ sources by *Sphinx*, a document processor specifically written for the Python documentation. @@ -15,4 +16,6 @@ See :ref:`reporting-bugs` for information how to report bugs in Python itself. -.. include:: ACKS \ No newline at end of file +.. % include the ACKS file here so that it can be maintained separately + +.. include:: ACKS Modified: doctools/trunk/Doc-26/c-api/concrete.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/concrete.rst (original) +++ doctools/trunk/Doc-26/c-api/concrete.rst Thu Aug 2 20:07:46 2007 @@ -2201,22 +2201,19 @@ .. cfunction:: PyObject* PyDict_Items(PyObject *p) Return a :ctype:`PyListObject` containing all the items from the dictionary, as - in the dictionary method :meth:`items` (see the Python Library Reference (XXX - reference: ../lib/lib.html)). + in the dictionary method :meth:`dict.items`. .. cfunction:: PyObject* PyDict_Keys(PyObject *p) Return a :ctype:`PyListObject` containing all the keys from the dictionary, as - in the dictionary method :meth:`keys` (see the Python Library Reference (XXX - reference: ../lib/lib.html)). + in the dictionary method :meth:`dict.keys`. .. cfunction:: PyObject* PyDict_Values(PyObject *p) Return a :ctype:`PyListObject` containing all the values from the dictionary - *p*, as in the dictionary method :meth:`values` (see the Python Library - Reference (XXX reference: ../lib/lib.html)). + *p*, as in the dictionary method :meth:`dict.values`. .. cfunction:: Py_ssize_t PyDict_Size(PyObject *p) Modified: doctools/trunk/Doc-26/c-api/intro.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/intro.rst (original) +++ doctools/trunk/Doc-26/c-api/intro.rst Thu Aug 2 20:07:46 2007 @@ -99,12 +99,11 @@ deallocated, they are typically static :ctype:`PyTypeObject` objects. All Python objects (even Python integers) have a :dfn:`type` and a -:dfn:`reference count`. An object's type determines what kind of object it is -(e.g., an integer, a list, or a user-defined function; there are many more as -explained in the Python Reference Manual (XXX reference: ../ref/ref.html)). For -each of the well-known types there is a macro to check whether an object is of -that type; for instance, ``PyList_Check(a)`` is true if (and only if) the object -pointed to by *a* is a Python list. +:dfn:`reference count`. An object's type determines what kind of object it is +(e.g., an integer, a list, or a user-defined function; there are many more as +explained in :ref:`types`). For each of the well-known types there is a macro +to check whether an object is of that type; for instance, ``PyList_Check(a)`` is +true if (and only if) the object pointed to by *a* is a Python list. .. _api-refcounts: Modified: doctools/trunk/Doc-26/c-api/newtypes.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/newtypes.rst (original) +++ doctools/trunk/Doc-26/c-api/newtypes.rst Thu Aug 2 20:07:46 2007 @@ -610,17 +610,17 @@ This field is inherited by subtypes. -PyNumberMethods \*tp_as_number; +.. cmember:: PyNumberMethods *tp_as_number; -XXX + XXX -PySequenceMethods \*tp_as_sequence; +.. cmember:: PySequenceMethods *tp_as_sequence; -XXX + XXX -PyMappingMethods \*tp_as_mapping; +.. cmember:: PyMappingMethods *tp_as_mapping; -XXX + XXX .. cmember:: hashfunc PyTypeObject.tp_hash @@ -842,12 +842,13 @@ .. data:: Py_TPFLAGS_HAVE_GC - This bit is set when the object supports garbage collection. If this bit is - set, instances must be created using :cfunc:`PyObject_GC_New` and destroyed - using :cfunc:`PyObject_GC_Del`. More information in section XXX about garbage - collection. This bit also implies that the GC-related fields - :attr:`tp_traverse` and :attr:`tp_clear` are present in the type object; but - those fields also exist when :const:`Py_TPFLAGS_HAVE_GC` is clear but + This bit is set when the object supports garbage collection. If this bit + is set, instances must be created using :cfunc:`PyObject_GC_New` and + destroyed using :cfunc:`PyObject_GC_Del`. More information in section + :ref:`supporting-cycle-detection`. This bit also implies that the + GC-related fields :attr:`tp_traverse` and :attr:`tp_clear` are present in + the type object; but those fields also exist when + :const:`Py_TPFLAGS_HAVE_GC` is clear but :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` is set. @@ -1598,9 +1599,8 @@ other objects, or which only store references to atomic types (such as numbers or strings), do not need to provide any explicit support for garbage collection. -An example showing the use of these interfaces can be found in "Supporting the -Cycle Collector (XXX reference: ../ext/example-cycle-support.html)" in Extending -and Embedding the Python Interpreter (XXX reference: ../ext/ext.html). +.. An example showing the use of these interfaces can be found in "Supporting the +.. Cycle Collector (XXX reference: ../ext/example-cycle-support.html)". To create a container type, the :attr:`tp_flags` field of the type object must include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the Modified: doctools/trunk/Doc-26/c-api/utilities.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/utilities.rst (original) +++ doctools/trunk/Doc-26/c-api/utilities.rst Thu Aug 2 20:07:46 2007 @@ -370,6 +370,7 @@ .. versionchanged:: 2.4 *version* indicates the file format. + The following functions allow marshalled values to be read back in. XXX What about error detection? It appears that reading past the end of the @@ -425,8 +426,8 @@ ===================================== These functions are useful when creating your own extensions functions and -methods. Additional information and examples are available in Extending and -Embedding the Python Interpreter (XXX reference: ../ext/ext.html). +methods. Additional information and examples are available in +:ref:`extending-index`. The first three of these functions described, :cfunc:`PyArg_ParseTuple`, :cfunc:`PyArg_ParseTupleAndKeywords`, and :cfunc:`PyArg_Parse`, all use *format Modified: doctools/trunk/Doc-26/distutils/index.rst ============================================================================== --- doctools/trunk/Doc-26/distutils/index.rst (original) +++ doctools/trunk/Doc-26/distutils/index.rst Thu Aug 2 20:07:46 2007 @@ -4,6 +4,8 @@ Distributing Python Modules ############################### +:Authors: Greg Ward, Anthony Baxter +:Email: distutils-sig(a)python.org :Release: |version| :Date: |today| Modified: doctools/trunk/Doc-26/distutils/introduction.rst ============================================================================== --- doctools/trunk/Doc-26/distutils/introduction.rst (original) +++ doctools/trunk/Doc-26/distutils/introduction.rst Thu Aug 2 20:07:46 2007 @@ -6,8 +6,8 @@ This document covers using the Distutils to distribute your Python modules, concentrating on the role of developer/distributor: if you're looking for -information on installing Python modules, you should refer to the Installing -Python Modules (XXX reference: ../inst/inst.html) manual. +information on installing Python modules, you should refer to the +:ref:`install-index` chapter. .. _distutils-concepts: Modified: doctools/trunk/Doc-26/extending/building.rst ============================================================================== --- doctools/trunk/Doc-26/extending/building.rst (original) +++ doctools/trunk/Doc-26/extending/building.rst Thu Aug 2 20:07:46 2007 @@ -52,7 +52,7 @@ information to build packages, and it specifies the contents of the package. Normally, a package will contain of addition modules, like Python source modules, documentation, subpackages, etc. Please refer to the distutils -documentation in Distributing Python Modules (XXX reference: ../dist/dist.html) +documentation in :ref:`distutils-index` to learn more about the features of distutils; this section explains building extension modules only. Modified: doctools/trunk/Doc-26/extending/extending.rst ============================================================================== --- doctools/trunk/Doc-26/extending/extending.rst (original) +++ doctools/trunk/Doc-26/extending/extending.rst Thu Aug 2 20:07:46 2007 @@ -117,8 +117,8 @@ traceback in case the error originated in Python code. These three variables are the C equivalents of the Python variables ``sys.exc_type``, ``sys.exc_value`` and ``sys.exc_traceback`` (see the section on module -:mod:`sys` in the Python Library Reference (XXX reference: ../lib/lib.html)). -It is important to know about them to understand how errors are passed around. +:mod:`sys` in the Python Library Reference). It is important to know about them +to understand how errors are passed around. The Python API defines a number of functions to set various types of exceptions. @@ -212,8 +212,7 @@ Note that the Python name for the exception object is :exc:`spam.error`. The :cfunc:`PyErr_NewException` function may create a class with the base class being :exc:`Exception` (unless another class is passed in instead of *NULL*), -described in the Python Library Reference (XXX reference: ../lib/lib.html) under -"Built-in Exceptions." +described in :ref:`bltin-exceptions`. Note also that the :cdata:`SpamError` variable retains a reference to the newly created exception class; this is intentional! Since the exception could be @@ -550,10 +549,9 @@ The *arg* argument must be a tuple object containing an argument list passed from Python to a C function. The *format* argument must be a format string, -whose syntax is explained in "Parsing arguments and building values (XXX -reference: ../api/arg-parsing.html)" in the Python/C API Reference Manual (XXX -reference: ../api/api.html). The remaining arguments must be addresses of -variables whose type is determined by the format string. +whose syntax is explained in :ref:`arg-parsing` in the Python/C API Reference +Manual. The remaining arguments must be addresses of variables whose type is +determined by the format string. Note that while :cfunc:`PyArg_ParseTuple` checks that the Python arguments have the required types, it cannot check the validity of the addresses of C variables @@ -816,7 +814,7 @@ The cycle detector is able to detect garbage cycles and can reclaim them so long as there are no finalizers implemented in Python (:meth:`__del__` methods). When there are such finalizers, the detector exposes the cycles through the -:mod:`gc` module (XXX reference: ../lib/module-gc.html) (specifically, the +:mod:`gc` module (specifically, the ``garbage`` variable in that module). The :mod:`gc` module also exposes a way to run the detector (the :func:`collect` function), as well as configuration interfaces and the ability to disable the detector at runtime. The cycle @@ -1257,8 +1255,7 @@ Finally it should be mentioned that CObjects offer additional functionality, which is especially useful for memory allocation and deallocation of the pointer stored in a CObject. The details are described in the Python/C API Reference -Manual (XXX reference: ../api/api.html) in the section "CObjects (XXX reference: -../api/cObjects.html)" and in the implementation of CObjects (files +Manual in the section :ref:`cobjects` and in the implementation of CObjects (files :file:`Include/cobject.h` and :file:`Objects/cobject.c` in the Python source code distribution). Modified: doctools/trunk/Doc-26/extending/newtypes.rst ============================================================================== --- doctools/trunk/Doc-26/extending/newtypes.rst (original) +++ doctools/trunk/Doc-26/extending/newtypes.rst Thu Aug 2 20:07:46 2007 @@ -1355,9 +1355,8 @@ ------------------------- Python supports a variety of *abstract* 'protocols;' the specific interfaces -provided to use these interfaces are documented in the Python/C API Reference -Manual (XXX reference: ../api/api.html) in the chapter "Abstract Objects Layer -(XXX reference: ../api/abstract.html)." +provided to use these interfaces are documented in :ref:`abstract`. + A number of these abstract interfaces were defined early in the development of the Python implementation. In particular, the number, mapping, and sequence Modified: doctools/trunk/Doc-26/extending/windows.rst ============================================================================== --- doctools/trunk/Doc-26/extending/windows.rst (original) +++ doctools/trunk/Doc-26/extending/windows.rst Thu Aug 2 20:07:46 2007 @@ -36,13 +36,11 @@ =================== There are two approaches to building extension modules on Windows, just as there -are on Unix: use the :mod:`distutils` (XXX reference: ../lib/module- -distutils.html) package to control the build process, or do things manually. -The distutils approach works well for most extensions; documentation on using -:mod:`distutils` (XXX reference: ../lib/module-distutils.html) to build and -package extension modules is available in Distributing Python Modules (XXX -reference: ../dist/dist.html). This section describes the manual approach to -building Python extensions written in C or C++. +are on Unix: use the :mod:`distutils` package to control the build process, or +do things manually. The distutils approach works well for most extensions; +documentation on using :mod:`distutils` to build and package extension modules +is available in :ref:`distutils-index`. This section describes the manual +approach to building Python extensions written in C or C++. To build extensions using these instructions, you need to have a copy of the Python sources of the same version as your installed Python. You will need Modified: doctools/trunk/Doc-26/install/index.rst ============================================================================== --- doctools/trunk/Doc-26/install/index.rst (original) +++ doctools/trunk/Doc-26/install/index.rst Thu Aug 2 20:07:46 2007 @@ -1,12 +1,14 @@ -.. _install-index: - .. highlightlang:: none +.. _install-index: + ***************************** Installing Python Modules ***************************** :Author: Greg Ward +:Release: |version| +:Date: |today| .. % TODO: .. % Fill in XXX comments @@ -21,8 +23,6 @@ .. % Finally, it might be useful to include all the material from my "Care .. % and Feeding of a Python Installation" talk in here somewhere. Yow! -XXX: input{boilerplate} :XXX - .. topic:: Abstract This document describes the Python Distribution Utilities ("Distutils") from the @@ -30,17 +30,6 @@ standard Python installation by building and installing third-party Python modules and extensions. -.. % \begin{abstract} -.. % \noindent -.. % Abstract this! -.. % \end{abstract} - -.. % The ugly "%begin{latexonly}" pseudo-environment suppresses the table -.. % of contents for HTML generation. -.. % -.. % begin{latexonly} -.. % end{latexonly} - .. _inst-intro: @@ -64,7 +53,7 @@ document; there will be some brief forays into using Python's interactive mode to explore your installation, but that's it. If you're looking for information on how to distribute your own Python modules so that others may use them, see -the Distributing Python Modules (XXX reference: ../dist/dist.html) manual. +the :ref:`distutils-index` manual. .. _inst-trivial-install: @@ -728,7 +717,7 @@ (2) On Unix, if the :envvar:`HOME` environment variable is not defined, the user's home directory will be determined with the :func:`getpwuid` function from the - standard :mod:`pwd` (XXX reference: ../lib/module-pwd.html) module. + standard :mod:`pwd` module. (3) I.e., in the current directory (usually the location of the setup script). @@ -1020,4 +1009,3 @@ .. [#] Then you have no POSIX emulation available, but you also don't need :file:`cygwin1.dll`. - Modified: doctools/trunk/Doc-26/library/array.rst ============================================================================== --- doctools/trunk/Doc-26/library/array.rst (original) +++ doctools/trunk/Doc-26/library/array.rst Thu Aug 2 20:07:46 2007 @@ -112,8 +112,7 @@ effectively make use of this information), it makes more sense to use the buffer interface supported by array objects. This method is maintained for backward compatibility and should be avoided in new code. The buffer interface is - documented in the Python/C API Reference Manual (XXX reference: - ../api/newTypes.html). + documented in :ref:`bufferobjects`. .. method:: array.byteswap() Modified: doctools/trunk/Doc-26/library/ast.rst ============================================================================== --- doctools/trunk/Doc-26/library/ast.rst (original) +++ doctools/trunk/Doc-26/library/ast.rst Thu Aug 2 20:07:46 2007 @@ -1,13 +1,11 @@ -.. % XXX Label can't be _ast? -.. % XXX Where should this section/chapter go? - - .. _ast: ********************* Abstract Syntax Trees ********************* +.. module:: _ast + .. sectionauthor:: Martin v. Löwis <martin(a)v.loewis.de> Modified: doctools/trunk/Doc-26/library/audioop.rst ============================================================================== --- doctools/trunk/Doc-26/library/audioop.rst (original) +++ doctools/trunk/Doc-26/library/audioop.rst Thu Aug 2 20:07:46 2007 @@ -191,11 +191,7 @@ .. function:: rms(fragment, width) - Return the root-mean-square of the fragment, i.e. :: - - XXX: translate this math - \catcode`_=8 - \sqrt{\frac{\sum{{S_{i}}^{2}}}{n}} + Return the root-mean-square of the fragment, i.e. ``sqrt(sum(S_i^2)/n)``. This is a measure of the power in an audio signal. Modified: doctools/trunk/Doc-26/library/codecs.rst ============================================================================== --- doctools/trunk/Doc-26/library/codecs.rst (original) +++ doctools/trunk/Doc-26/library/codecs.rst Thu Aug 2 20:07:46 2007 @@ -1141,11 +1141,7 @@ .. module:: encodings.idna :synopsis: Internationalized Domain Names implementation - - -.. % XXX The next line triggers a formatting bug, so it's commented out -.. % until that can be fixed. -.. % \moduleauthor{Martin v. L\"owis} +.. moduleauthor:: Martin v. Löwis .. versionadded:: 2.3 @@ -1204,13 +1200,10 @@ :mod:`encodings.utf_8_sig` --- UTF-8 codec with BOM signature ------------------------------------------------------------- -.. module:: encodings.utf-8-sig +.. module:: encodings.utf_8_sig :synopsis: UTF-8 codec with BOM signature .. moduleauthor:: Walter Dörwald - -.. % XXX utf_8_sig gives TeX errors - .. versionadded:: 2.5 This module implements a variant of the UTF-8 codec: On encoding a UTF-8 encoded Modified: doctools/trunk/Doc-26/library/distutils.rst ============================================================================== --- doctools/trunk/Doc-26/library/distutils.rst (original) +++ doctools/trunk/Doc-26/library/distutils.rst Thu Aug 2 20:07:46 2007 @@ -13,23 +13,17 @@ 100%-pure Python, or may be extension modules written in C, or may be collections of Python packages which include modules coded in both Python and C. -This package is discussed in two separate documents which are included in the -Python documentation package. To learn about distributing new modules using the -:mod:`distutils` facilities, read Distributing Python Modules (XXX reference: -../dist/dist.html); this includes documentation needed to extend distutils. To -learn about installing Python modules, whether or not the author made use of the -:mod:`distutils` package, read Installing Python Modules (XXX reference: -../inst/inst.html). +This package is discussed in two separate chapters: .. seealso:: - `Distributing Python Modules <../dist/dist.html>`_ + :ref:`distutils-index` The manual for developers and packagers of Python modules. This describes how to prepare :mod:`distutils`\ -based packages so that they may be easily installed into an existing Python installation. - `Installing Python Modules <../inst/inst.html>`_ + :ref:`install-index` An "administrators" manual which includes information on installing modules into an existing Python installation. You do not need to be a Python programmer to read this manual. Modified: doctools/trunk/Doc-26/library/exceptions.rst ============================================================================== --- doctools/trunk/Doc-26/library/exceptions.rst (original) +++ doctools/trunk/Doc-26/library/exceptions.rst Thu Aug 2 20:07:46 2007 @@ -1,3 +1,4 @@ +.. _bltin-exceptions: Built-in Exceptions =================== @@ -40,8 +41,8 @@ The built-in exception classes can be sub-classed to define new exceptions; programmers are encouraged to at least derive new exceptions from the :exc:`Exception` class and not :exc:`BaseException`. More information on -defining exceptions is available in the Python Tutorial (XXX reference: -../tut/tut.html) under the heading "User-defined Exceptions." +defining exceptions is available in the Python Tutorial under +:ref:`tut-userexceptions`. The following exceptions are only used as base classes for other exceptions. Modified: doctools/trunk/Doc-26/library/functions.rst ============================================================================== --- doctools/trunk/Doc-26/library/functions.rst (original) +++ doctools/trunk/Doc-26/library/functions.rst Thu Aug 2 20:07:46 2007 @@ -154,8 +154,7 @@ def f(cls, arg1, arg2, ...): ... The ``@classmethod`` form is a function decorator -- see the description of - function definitions in chapter 7 of the Python Reference Manual (XXX reference: - ../ref/ref.html) for details. + function definitions in :ref:`function` for details. It can be called either on the class (such as ``C.f()``) or on an instance (such as ``C().f()``). The instance is ignored except for its class. If a class @@ -166,8 +165,7 @@ see :func:`staticmethod` in this section. For more information on class methods, consult the documentation on the standard - type hierarchy in chapter 3 of the Python Reference Manual (XXX reference: - ../ref/types.html) (at the bottom). + type hierarchy in :ref:`types`. .. versionadded:: 2.2 @@ -1063,8 +1061,7 @@ def f(arg1, arg2, ...): ... The ``@staticmethod`` form is a function decorator -- see the description of - function definitions in chapter 7 of the Python Reference Manual (XXX reference: - ../ref/function.html) for details. + function definitions in :ref:`function` for details. It can be called either on the class (such as ``C.f()``) or on an instance (such as ``C().f()``). The instance is ignored except for its class. @@ -1073,8 +1070,7 @@ advanced concept, see :func:`classmethod` in this section. For more information on static methods, consult the documentation on the - standard type hierarchy in chapter 3 of the Python Reference Manual (XXX - reference: ../ref/types.html) (at the bottom). + standard type hierarchy in :ref:`types`. .. versionadded:: 2.2 Modified: doctools/trunk/Doc-26/library/objects.rst ============================================================================== --- doctools/trunk/Doc-26/library/objects.rst (original) +++ doctools/trunk/Doc-26/library/objects.rst Thu Aug 2 20:07:46 2007 @@ -22,8 +22,8 @@ in order of ascending priority (within a table) and grouping operators that have the same priority in the same box. Binary operators of the same priority group from left to right. (Unary operators group from right to left, but there you -have no real choice.) See chapter 5 of the Python Reference Manual (XXX -reference: ../ref/ref.html) for the complete picture on operator priorities. +have no real choice.) See :ref:`operator-summary` for the complete picture on +operator priorities. .. rubric:: Footnotes Modified: doctools/trunk/Doc-26/library/operator.rst ============================================================================== --- doctools/trunk/Doc-26/library/operator.rst (original) +++ doctools/trunk/Doc-26/library/operator.rst Thu Aug 2 20:07:46 2007 @@ -36,13 +36,12 @@ __gt__(a, b) Perform "rich comparisons" between *a* and *b*. Specifically, ``lt(a, b)`` is - equivalent to ``a < b``, ``le(a, b)`` is equivalent to ``a <= b``, ``eq(a, b)`` - is equivalent to ``a == b``, ``ne(a, b)`` is equivalent to ``a != b``, ``gt(a, - b)`` is equivalent to ``a > b`` and ``ge(a, b)`` is equivalent to ``a >= b``. - Note that unlike the built-in :func:`cmp`, these functions can return any value, - which may or may not be interpretable as a Boolean value. See the Python - Reference Manual (XXX reference: ../ref/ref.html) for more information about - rich comparisons. + equivalent to ``a < b``, ``le(a, b)`` is equivalent to ``a <= b``, ``eq(a, + b)`` is equivalent to ``a == b``, ``ne(a, b)`` is equivalent to ``a != b``, + ``gt(a, b)`` is equivalent to ``a > b`` and ``ge(a, b)`` is equivalent to ``a + >= b``. Note that unlike the built-in :func:`cmp`, these functions can + return any value, which may or may not be interpretable as a Boolean value. + See :ref:`comparisons` for more information about rich comparisons. .. versionadded:: 2.2 Modified: doctools/trunk/Doc-26/library/parser.rst ============================================================================== --- doctools/trunk/Doc-26/library/parser.rst (original) +++ doctools/trunk/Doc-26/library/parser.rst Thu Aug 2 20:07:46 2007 @@ -32,7 +32,7 @@ Most importantly, a good understanding of the Python grammar processed by the internal parser is required. For full information on the language syntax, refer -to the Python Language Reference (XXX reference: ../ref/ref.html). The parser +to :ref:`reference-index`. The parser itself is created from a grammar specification defined in the file :file:`Grammar/Grammar` in the standard Python distribution. The parse trees stored in the AST objects created by this module are the actual output from the Modified: doctools/trunk/Doc-26/library/pdb.rst ============================================================================== --- doctools/trunk/Doc-26/library/pdb.rst (original) +++ doctools/trunk/Doc-26/library/pdb.rst Thu Aug 2 20:07:46 2007 @@ -406,6 +406,5 @@ Note that as an exception is propagated down the chain of callers, an ``'exception'`` event is generated at each level. -For more information on code and frame objects, refer to the Python Reference -Manual (XXX reference: ../ref/ref.html). +For more information on code and frame objects, refer to :ref:`types`. Modified: doctools/trunk/Doc-26/library/stdtypes.rst ============================================================================== --- doctools/trunk/Doc-26/library/stdtypes.rst (original) +++ doctools/trunk/Doc-26/library/stdtypes.rst Thu Aug 2 20:07:46 2007 @@ -26,10 +26,7 @@ practically all objects can be compared, tested for truth value, and converted to a string (with the :func:`repr` function or the slightly different :func:`str` function). The latter function is implicitly used when an object is -written by the :keyword:`print` statement. (Information on the :keyword:`print` -statement (XXX reference: ../ref/print.html) and other language statements can -be found in the Python Reference Manual (XXX reference: ../ref/ref.html) and the -Python Tutorial (XXX reference: ../tut/tut.html).) +written by the :func:`print` function. .. _truth: @@ -186,10 +183,9 @@ .. index:: single: __cmp__() (instance method) -Instances of a class normally compare as non-equal unless the class defines the -:meth:`__cmp__` method. Refer to the Python Reference Manual (XXX reference: -../ref/customization.html) for information on the use of this method to effect -object comparisons. +Instances of a class normally compare as non-equal unless the class defines the +:meth:`__cmp__` method. Refer to :ref:`customization`) for information on the +use of this method to effect object comparisons. **Implementation note:** Objects of different types except numbers are ordered by their type names; objects of the same types that don't support proper @@ -498,12 +494,11 @@ object: list String literals are written in single or double quotes: ``'xyzzy'``, -``"frobozz"``. See chapter 2 of the Python Reference Manual (XXX reference: -../ref/strings.html) for more about string literals. Unicode strings are much -like strings, but are specified in the syntax using a preceding ``'u'`` -character: ``u'abc'``, ``u"def"``. Lists are constructed with square brackets, -separating items with commas: ``[a, b, c]``. Tuples are constructed by the -comma operator (not within square brackets), with or without enclosing +``"frobozz"``. See :ref:`strings` for more about string literals. Unicode +strings are much like strings, but are specified in the syntax using a preceding +``'u'`` character: ``u'abc'``, ``u"def"``. Lists are constructed with square +brackets, separating items with commas: ``[a, b, c]``. Tuples are constructed +by the comma operator (not within square brackets), with or without enclosing parentheses, but an empty tuple must have the enclosing parentheses, such as ``a, b, c`` or ``()``. A single item tuple must have a trailing comma, such as ``(d,)``. @@ -2133,8 +2128,7 @@ .. _classes and instances: -See chapters 3 and 7 of the Python Reference Manual (XXX reference: -../ref/ref.html) for these. +See :ref:`objects` and :ref:`class` for these. .. _typesfunctions: @@ -2149,8 +2143,7 @@ defined functions. Both support the same operation (to call the function), but the implementation is different, hence the different object types. -See the Python Reference Manual (XXX reference: ../ref/ref.html) for more -information. +See :ref:`function` for more information. .. _typesmethods: @@ -2192,8 +2185,7 @@ c = C() c.method.im_func.whoami = 'my name is c' -See the Python Reference Manual (XXX reference: ../ref/ref.html) for more -information. +See :ref:`types` for more information. .. _bltin-code-objects: @@ -2221,8 +2213,7 @@ A code object can be executed or evaluated by passing it (instead of a source string) to the :keyword:`exec` statement or the built-in :func:`eval` function. -See the Python Reference Manual (XXX reference: ../ref/ref.html) for more -information. +See :ref:`types` for more information. .. _bltin-type-objects: @@ -2259,9 +2250,9 @@ The Ellipsis Object ------------------- -This object is used by extended slice notation (see the Python Reference Manual -(XXX reference: ../ref/ref.html)). It supports no special operations. There is -exactly one ellipsis object, named :const:`Ellipsis` (a built-in name). +This object is used by extended slice notation (see :ref:`slicings`). It +supports no special operations. There is exactly one ellipsis object, named +:const:`Ellipsis` (a built-in name). It is written as ``Ellipsis``. @@ -2290,9 +2281,8 @@ Internal Objects ---------------- -See the Python Reference Manual (XXX reference: ../ref/ref.html) for this -information. It describes stack frame objects, traceback objects, and slice -objects. +See :ref:`types` for this information. It describes stack frame objects, +traceback objects, and slice objects. .. _specialattrs: @@ -2342,8 +2332,8 @@ .. rubric:: Footnotes -.. [#] Additional information on these special methods may be found in the Python - Reference Manual (XXX reference: ../ref/ref.html). +.. [#] Additional information on these special methods may be found in the Python + Reference Manual (:ref:`customization`). .. [#] As a consequence, the list ``[1, 2]`` is considered equal to ``[1.0, 2.0]``, and similarly for tuples. Modified: doctools/trunk/Doc-26/library/warnings.rst ============================================================================== --- doctools/trunk/Doc-26/library/warnings.rst (original) +++ doctools/trunk/Doc-26/library/warnings.rst Thu Aug 2 20:07:46 2007 @@ -16,8 +16,8 @@ might want to issue a warning when a program uses an obsolete module. Python programmers issue warnings by calling the :func:`warn` function defined -in this module. (C programmers use :cfunc:`PyErr_Warn`; see the Python/C API -Reference Manual (XXX reference: ../api/exceptionHandling.html) for details). +in this module. (C programmers use :cfunc:`PyErr_Warn`; see +:ref:`exceptionhandling` for details). Warning messages are normally written to ``sys.stderr``, but their disposition can be changed flexibly, from ignoring all warnings to turning them into Modified: doctools/trunk/Doc-26/library/weakref.rst ============================================================================== --- doctools/trunk/Doc-26/library/weakref.rst (original) +++ doctools/trunk/Doc-26/library/weakref.rst Thu Aug 2 20:07:46 2007 @@ -65,14 +65,8 @@ obj = Dict(red=1, green=2, blue=3) # this object is weak referencable -Extension types can easily be made to support weak references; see "Weak -Reference Support (XXX reference: ../ext/weakref-support.html)" in Extending and -Embedding the Python Interpreter (XXX reference: ../ext/ext.html). - -.. % The referenced section used to appear in this document with the -.. % \label weakref-extension. It would be good to be able to generate a -.. % redirect for the corresponding HTML page (weakref-extension.html) -.. % for on-line versions of this document. +Extension types can easily be made to support weak references; see +:ref:`weakref-support`. .. class:: ref(object[, callback]) Modified: doctools/trunk/Doc-26/library/webbrowser.rst ============================================================================== --- doctools/trunk/Doc-26/library/webbrowser.rst (original) +++ doctools/trunk/Doc-26/library/webbrowser.rst Thu Aug 2 20:07:46 2007 @@ -151,9 +151,7 @@ Only on Windows platforms. (3) - Only on MacOS platforms; requires the standard MacPython :mod:`ic` module, - described in the Macintosh Library Modules (XXX reference: ../mac/module- - ic.html) manual. + Only on MacOS platforms; requires the standard MacPython :mod:`ic` module. (4) Only on MacOS X platform. Modified: doctools/trunk/Doc-26/library/xml.etree.elementtree.rst ============================================================================== --- doctools/trunk/Doc-26/library/xml.etree.elementtree.rst (original) +++ doctools/trunk/Doc-26/library/xml.etree.elementtree.rst Thu Aug 2 20:07:46 2007 @@ -267,7 +267,7 @@ .. method:: Element.remove(subelement) - Removes *subelement* from the element. Unlike the findXXX methods this method + Removes *subelement* from the element. Unlike the findXYZ methods this method compares elements based on the instance identity, not on tag value or contents. Element objects also support the following sequence type methods for working Modified: doctools/trunk/Doc-26/library/xml.sax.handler.rst ============================================================================== --- doctools/trunk/Doc-26/library/xml.sax.handler.rst (original) +++ doctools/trunk/Doc-26/library/xml.sax.handler.rst Thu Aug 2 20:07:46 2007 @@ -207,7 +207,7 @@ information to the application to expand prefixes in those contexts itself, if necessary. - .. % % XXX This is not really the default, is it? MvL + .. % XXX This is not really the default, is it? MvL Note that :meth:`startPrefixMapping` and :meth:`endPrefixMapping` events are not guaranteed to be properly nested relative to each-other: all @@ -232,7 +232,7 @@ The *name* parameter contains the raw XML 1.0 name of the element type as a string and the *attrs* parameter holds an object of the :class:`Attributes` - interface (XXX reference: attributes-objects.html) containing the attributes of + interface (see :ref:`attributes-objects`) containing the attributes of the element. The object passed as *attrs* may be re-used by the parser; holding on to a reference to it is not a reliable way to keep a copy of the attributes. To keep a copy of the attributes, use the :meth:`copy` method of the *attrs* @@ -254,7 +254,7 @@ The *name* parameter contains the name of the element type as a ``(uri, localname)`` tuple, the *qname* parameter contains the raw XML 1.0 name used in the source document, and the *attrs* parameter holds an instance of the - :class:`AttributesNS` interface (XXX reference: attributes-ns-objects.html) + :class:`AttributesNS` interface (see :ref:`attributes-ns-objects`) containing the attributes of the element. If no namespace is associated with the element, the *uri* component of *name* will be ``None``. The object passed as *attrs* may be re-used by the parser; holding on to a reference to it is not Modified: doctools/trunk/Doc-26/maclib/mac.rst ============================================================================== --- doctools/trunk/Doc-26/maclib/mac.rst (original) +++ doctools/trunk/Doc-26/maclib/mac.rst Thu Aug 2 20:07:46 2007 @@ -11,8 +11,8 @@ This module is the Mac OS 9 (and earlier) implementation of the :mod:`os.path` module. It can be used to manipulate old-style Macintosh pathnames on Mac OS X -(or any other platform). Refer to the Python Library Reference (XXX reference: -../lib/lib.html) for documentation of :mod:`os.path`. +(or any other platform). Refer to the Python Library Reference for documentation +of :mod:`os.path`. The following functions are available in this module: :func:`normcase`, :func:`normpath`, :func:`isabs`, :func:`join`, :func:`split`, :func:`isdir`, Modified: doctools/trunk/Doc-26/reference/datamodel.rst ============================================================================== --- doctools/trunk/Doc-26/reference/datamodel.rst (original) +++ doctools/trunk/Doc-26/reference/datamodel.rst Thu Aug 2 20:07:46 2007 @@ -60,8 +60,8 @@ reference-counting scheme with (optional) delayed detection of cyclically linked garbage, which collects most objects as soon as they become unreachable, but is not guaranteed to collect garbage containing circular references. See the -Python Library Reference (XXX reference: ../lib/module-gc.html) for information -on controlling the collection of cyclic garbage.) +documentation of the :mod:`gc` module for information on controlling the +collection of cyclic garbage.) Note that the use of the implementation's tracing or debugging facilities may keep objects alive that would normally be collectable. Also note that catching @@ -862,12 +862,12 @@ single: stderr (in module sys) A file object represents an open file. File objects are created by the - :func:`open` built-in function, and also by :func:`os.popen`, :func:`os.fdopen`, - and the :meth:`makefile` method of socket objects (and perhaps by other - functions or methods provided by extension modules). The objects ``sys.stdin``, - ``sys.stdout`` and ``sys.stderr`` are initialized to file objects corresponding - to the interpreter's standard input, output and error streams. See the Python - Library Reference (XXX reference: ../lib/lib.html) for complete documentation of + :func:`open` built-in function, and also by :func:`os.popen`, + :func:`os.fdopen`, and the :meth:`makefile` method of socket objects (and + perhaps by other functions or methods provided by extension modules). The + objects ``sys.stdin``, ``sys.stdout`` and ``sys.stderr`` are initialized to + file objects corresponding to the interpreter's standard input, output and + error streams. See :ref:`bltin-file-objects` for complete documentation of file objects. Internal types @@ -1217,24 +1217,25 @@ .. note:: - ``del x`` doesn't directly call ``x.__del__()`` --- the former decrements the - reference count for ``x`` by one, and the latter is only called when ``x``'s - reference count reaches zero. Some common situations that may prevent the - reference count of an object from going to zero include: circular references - between objects (e.g., a doubly-linked list or a tree data structure with parent - and child pointers); a reference to the object on the stack frame of a function - that caught an exception (the traceback stored in ``sys.exc_traceback`` keeps - the stack frame alive); or a reference to the object on the stack frame that - raised an unhandled exception in interactive mode (the traceback stored in - ``sys.last_traceback`` keeps the stack frame alive). The first situation can - only be remedied by explicitly breaking the cycles; the latter two situations - can be resolved by storing ``None`` in ``sys.exc_traceback`` or - ``sys.last_traceback``. Circular references which are garbage are detected when - the option cycle detector is enabled (it's on by default), but can only be - cleaned up if there are no Python-level :meth:`__del__` methods involved. Refer - to the documentation for the :mod:`gc` module (XXX reference: ../lib/module- - gc.html) for more information about how :meth:`__del__` methods are handled by - the cycle detector, particularly the description of the ``garbage`` value. + ``del x`` doesn't directly call ``x.__del__()`` --- the former decrements + the reference count for ``x`` by one, and the latter is only called when + ``x``'s reference count reaches zero. Some common situations that may + prevent the reference count of an object from going to zero include: + circular references between objects (e.g., a doubly-linked list or a tree + data structure with parent and child pointers); a reference to the object + on the stack frame of a function that caught an exception (the traceback + stored in ``sys.exc_traceback`` keeps the stack frame alive); or a + reference to the object on the stack frame that raised an unhandled + exception in interactive mode (the traceback stored in + ``sys.last_traceback`` keeps the stack frame alive). The first situation + can only be remedied by explicitly breaking the cycles; the latter two + situations can be resolved by storing ``None`` in ``sys.exc_traceback`` or + ``sys.last_traceback``. Circular references which are garbage are + detected when the option cycle detector is enabled (it's on by default), + but can only be cleaned up if there are no Python-level :meth:`__del__` + methods involved. Refer to the documentation for the :mod:`gc` module for + more information about how :meth:`__del__` methods are handled by the + cycle detector, particularly the description of the ``garbage`` value. .. warning:: @@ -1824,9 +1825,7 @@ should also be made available as the method :meth:`iterkeys`. Iterator objects also need to implement this method; they are required to return - themselves. For more information on iterator objects, see "Iterator Types (XXX - reference: ../lib/typeiter.html)" in the Python Library Reference (XXX - reference: ../lib/lib.html). + themselves. For more information on iterator objects, see :ref:`typeiter`. The membership test operators (:keyword:`in` and :keyword:`not in`) are normally implemented as an iteration through a sequence. However, container objects can @@ -2231,9 +2230,7 @@ Typical uses of context managers include saving and restoring various kinds of global state, locking and unlocking resources, closing opened files, etc. -For more information on context managers, see "Context Types (XXX reference: -../lib/typecontextmanager.html)" in the Python Library Reference (XXX reference: -../lib/lib.html). +For more information on context managers, see :ref:`typecontextmanager`. .. method:: context manager.__enter__(self) Modified: doctools/trunk/Doc-26/reference/expressions.rst ============================================================================== --- doctools/trunk/Doc-26/reference/expressions.rst (original) +++ doctools/trunk/Doc-26/reference/expressions.rst Thu Aug 2 20:07:46 2007 @@ -747,9 +747,8 @@ object: method object: function - The result is up to the interpreter; see the Python Library Reference (XXX - reference: ../lib/built-in-funcs.html) for the descriptions of built-in - functions and methods. + The result is up to the interpreter; see :ref:`built-in-funcs` for the + descriptions of built-in functions and methods. a class object: .. index:: @@ -903,8 +902,7 @@ In addition to performing the modulo operation on numbers, the ``%`` operator is also overloaded by string and unicode objects to perform string formatting (also known as interpolation). The syntax for string formatting is described in the -Python Library Reference (XXX reference: ../lib/typesseq-strings.html), section -"Sequence Types". +Python Library Reference, section :ref:`typesseq-strings`. .. deprecated:: 2.3 The floor division operator, the modulo operator, and the :func:`divmod` @@ -1241,7 +1239,7 @@ expr3, expr4 = expr1, expr2 -.. _summary: +.. _operator-summary: Summary ======= Modified: doctools/trunk/Doc-26/reference/introduction.rst ============================================================================== --- doctools/trunk/Doc-26/reference/introduction.rst (original) +++ doctools/trunk/Doc-26/reference/introduction.rst Thu Aug 2 20:07:46 2007 @@ -29,9 +29,9 @@ you'll find short "implementation notes" sprinkled throughout the text. Every Python implementation comes with a number of built-in and standard -modules. These are not documented here, but in the separate Python Library -Reference (XXX reference: ../lib/lib.html) document. A few built-in modules are -mentioned when they interact in a significant way with the language definition. +modules. These are documented in :ref:`library-index`. A few built-in modules +are mentioned when they interact in a significant way with the language +definition. .. _implementations: Modified: doctools/trunk/Doc-26/reference/lexical_analysis.rst ============================================================================== --- doctools/trunk/Doc-26/reference/lexical_analysis.rst (original) +++ doctools/trunk/Doc-26/reference/lexical_analysis.rst Thu Aug 2 20:07:46 2007 @@ -390,9 +390,9 @@ .. note:: - The name ``_`` is often used in conjunction with internationalization; refer to - the documentation for the :mod:`gettext` module (XXX reference: ../lib/module- - gettext.html) for more information on this convention. + The name ``_`` is often used in conjunction with internationalization; + refer to the documentation for the :mod:`gettext` module for more + information on this convention. ``__*__`` System-defined names. These names are defined by the interpreter and its Modified: doctools/trunk/Doc-26/reference/simple_stmts.rst ============================================================================== --- doctools/trunk/Doc-26/reference/simple_stmts.rst (original) +++ doctools/trunk/Doc-26/reference/simple_stmts.rst Thu Aug 2 20:07:46 2007 @@ -760,9 +760,8 @@ .. index:: builtin: __import__ The built-in function :func:`__import__` is provided to support applications -that determine which modules need to be loaded dynamically; refer to Built-in -Functions (XXX reference: ../lib/built-in-funcs.html) in the Python Library -Reference (XXX reference: ../lib/lib.html) for additional information. +that determine which modules need to be loaded dynamically; refer to +:ref:`built-in-funcs` for additional information. .. _future: @@ -833,8 +832,7 @@ a future statement will, by default, use the new syntax or semantics associated with the future statement. This can, starting with Python 2.2 be controlled by optional arguments to :func:`compile` --- see the documentation of that function -in the Python Library Reference (XXX reference: ../lib/built-in-funcs.html) for -details. +for details. A future statement typed at an interactive interpreter prompt will take effect for the rest of the interpreter session. If an interpreter is started with the Modified: doctools/trunk/Doc-26/tutorial/controlflow.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/controlflow.rst (original) +++ doctools/trunk/Doc-26/tutorial/controlflow.rst Thu Aug 2 20:07:46 2007 @@ -393,12 +393,12 @@ TypeError: function() got multiple values for keyword argument 'a' When a final formal parameter of the form ``**name`` is present, it receives a -dictionary (XXX reference: ../lib/typesmapping.html) containing all keyword -arguments except for those corresponding to a formal parameter. This may be -combined with a formal parameter of the form ``*name`` (described in the next -subsection) which receives a tuple containing the positional arguments beyond -the formal parameter list. (``*name`` must occur before ``**name``.) For -example, if we define a function like this:: +dictionary (see :ref:`typesmapping`) containing all keyword arguments except for +those corresponding to a formal parameter. This may be combined with a formal +parameter of the form ``*name`` (described in the next subsection) which +receives a tuple containing the positional arguments beyond the formal parameter +list. (``*name`` must occur before ``**name``.) For example, if we define a +function like this:: def cheeseshop(kind, *arguments, **keywords): print "-- Do you have any", kind, '?' Modified: doctools/trunk/Doc-26/tutorial/datastructures.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/datastructures.rst (original) +++ doctools/trunk/Doc-26/tutorial/datastructures.rst Thu Aug 2 20:07:46 2007 @@ -47,8 +47,7 @@ is specified, ``a.pop()`` removes and returns the last item in the list. (The square brackets around the *i* in the method signature denote that the parameter is optional, not that you should type square brackets at that position. You - will see this notation frequently in the Python Library Reference (XXX - reference: ../lib/lib.html).) + will see this notation frequently in the Python Library Reference.) .. method:: list.index(x) @@ -302,10 +301,10 @@ ==================== We saw that lists and strings have many common properties, such as indexing and -slicing operations. They are two examples of *sequence* data types (XXX -reference: ../lib/typesseq.html). Since Python is an evolving language, other -sequence data types may be added. There is also another standard sequence data -type: the *tuple*. +slicing operations. They are two examples of *sequence* data types (see +:ref:`typesseq`). Since Python is an evolving language, other sequence data +types may be added. There is also another standard sequence data type: the +*tuple*. A tuple consists of a number of values separated by commas, for instance:: @@ -404,9 +403,9 @@ Dictionaries ============ -Another useful data type built into Python is the *dictionary* (XXX reference: -../lib/typesmapping.html). Dictionaries are sometimes found in other languages -as "associative memories" or "associative arrays". Unlike sequences, which are +Another useful data type built into Python is the *dictionary* (see +:ref:`typesmapping`). Dictionaries are sometimes found in other languages as +"associative memories" or "associative arrays". Unlike sequences, which are indexed by a range of numbers, dictionaries are indexed by *keys*, which can be any immutable type; strings and numbers can always be keys. Tuples can be used as keys if they contain only strings, numbers, or tuples; if a tuple contains Modified: doctools/trunk/Doc-26/tutorial/errors.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/errors.rst (original) +++ doctools/trunk/Doc-26/tutorial/errors.rst Thu Aug 2 20:07:46 2007 @@ -71,8 +71,7 @@ traceback listing source lines; however, it will not display lines read from standard input. -The Python Library Reference (XXX reference: ../lib/module-exceptions.html) -lists the built-in exceptions and their meanings. +:ref:`bltin-exceptions` lists the built-in exceptions and their meanings. .. _tut-handling: Modified: doctools/trunk/Doc-26/tutorial/glossary.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/glossary.rst (original) +++ doctools/trunk/Doc-26/tutorial/glossary.rst Thu Aug 2 20:07:46 2007 @@ -118,9 +118,8 @@ from __future__ import division the expression ``11/4`` would evaluate to ``2.75``. By importing the - :mod:`__future__` (XXX reference: ../lib/module-future.html) module and - evaluating its variables, you can see when a new feature was first added to the - language and when it will become the default:: + :mod:`__future__` module and evaluating its variables, you can see when a new + feature was first added to the language and when it will become the default:: >>> import __future__ >>> __future__.division @@ -296,9 +295,8 @@ namespaces. Namespaces also aid readability and maintainability by making it clear which module implements a function. For instance, writing :func:`random.seed` or :func:`itertools.izip` makes it clear that those - functions are implemented by the :mod:`random` (XXX reference: ../lib/module- - random.html) and :mod:`itertools` (XXX reference: ../lib/module-itertools.html) - modules respectively. + functions are implemented by the :mod:`random` and :mod:`itertools` modules + respectively. .. index:: single: nested scope Modified: doctools/trunk/Doc-26/tutorial/inputoutput.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/inputoutput.rst (original) +++ doctools/trunk/Doc-26/tutorial/inputoutput.rst Thu Aug 2 20:07:46 2007 @@ -323,14 +323,13 @@ complicated. Rather than have users be constantly writing and debugging code to save -complicated data types, Python provides a standard module called :mod:`pickle` -(XXX reference: ../lib/module-pickle.html). This is an amazing module that can -take almost any Python object (even some forms of Python code!), and convert it -to a string representation; this process is called :dfn:`pickling`. -Reconstructing the object from the string representation is called -:dfn:`unpickling`. Between pickling and unpickling, the string representing the -object may have been stored in a file or data, or sent over a network connection -to some distant machine. +complicated data types, Python provides a standard module called :mod:`pickle`. +This is an amazing module that can take almost any Python object (even some +forms of Python code!), and convert it to a string representation; this process +is called :dfn:`pickling`. Reconstructing the object from the string +representation is called :dfn:`unpickling`. Between pickling and unpickling, +the string representing the object may have been stored in a file or data, or +sent over a network connection to some distant machine. If you have an object ``x``, and a file object ``f`` that's been opened for writing, the simplest way to pickle the object takes only one line of code:: @@ -344,15 +343,12 @@ (There are other variants of this, used when pickling many objects or when you don't want to write the pickled data to a file; consult the complete -documentation for :mod:`pickle` (XXX reference: ../lib/module-pickle.html) in -the Python Library Reference (XXX reference: ../lib/).) +documentation for :mod:`pickle` in the Python Library Reference.) -:mod:`pickle` (XXX reference: ../lib/module-pickle.html) is the standard way to -make Python objects which can be stored and reused by other programs or by a -future invocation of the same program; the technical term for this is a -:dfn:`persistent` object. Because :mod:`pickle` (XXX reference: ../lib/module- -pickle.html) is so widely used, many authors who write Python extensions take -care to ensure that new data types such as matrices can be properly pickled and -unpickled. +:mod:`pickle` is the standard way to make Python objects which can be stored and +reused by other programs or by a future invocation of the same program; the +technical term for this is a :dfn:`persistent` object. Because :mod:`pickle` is +so widely used, many authors who write Python extensions take care to ensure +that new data types such as matrices can be properly pickled and unpickled. Modified: doctools/trunk/Doc-26/tutorial/interactive.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/interactive.rst (original) +++ doctools/trunk/Doc-26/tutorial/interactive.rst Thu Aug 2 20:07:46 2007 @@ -115,8 +115,8 @@ the startup file is executed in the same namespace as the interactive commands, and removing the names avoids creating side effects in the interactive environment. You may find it convenient to keep some of the imported modules, -such as :mod:`os` (XXX reference: ../lib/module-os.html), which turn out to be -needed in most sessions with the interpreter. :: +such as :mod:`os`, which turn out to be needed in most sessions with the +interpreter. :: # Add auto-completion and a stored history file of commands to your Python # interactive interpreter. Requires Python 2.0+, readline. Autocomplete is Modified: doctools/trunk/Doc-26/tutorial/interpreter.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/interpreter.rst (original) +++ doctools/trunk/Doc-26/tutorial/interpreter.rst Thu Aug 2 20:07:46 2007 @@ -182,9 +182,8 @@ With that declaration, all characters in the source file will be treated as having the encoding *encoding*, and it will be possible to directly write Unicode string literals in the selected encoding. The list of possible -encodings can be found in the Python Library Reference (XXX reference: -../lib/lib.html), in the section on :mod:`codecs` (XXX reference: ../lib/module- -codecs.html). +encodings can be found in the Python Library Reference, in the section on +:mod:`codecs`. For example, to write Unicode literals including the Euro currency symbol, the ISO-8859-15 encoding can be used, with the Euro symbol having the ordinal value Modified: doctools/trunk/Doc-26/tutorial/modules.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/modules.rst (original) +++ doctools/trunk/Doc-26/tutorial/modules.rst Thu Aug 2 20:07:46 2007 @@ -215,9 +215,8 @@ .. index:: module: compileall -* The module :mod:`compileall` (XXX reference: ../lib/module-compileall.html) - can create :file:`.pyc` files (or :file:`.pyo` files when :option:`-O` is used) - for all modules in a directory. +* The module :mod:`compileall` can create :file:`.pyc` files (or :file:`.pyo` + files when :option:`-O` is used) for all modules in a directory. .. % @@ -230,15 +229,14 @@ .. index:: module: sys Python comes with a library of standard modules, described in a separate -document, the Python Library Reference (XXX reference: ../lib/lib.html) -("Library Reference" hereafter). Some modules are built into the interpreter; -these provide access to operations that are not part of the core of the language -but are nevertheless built in, either for efficiency or to provide access to -operating system primitives such as system calls. The set of such modules is a -configuration option which also depends on the underlying platform For example, -the :mod:`winreg` module is only provided on Windows systems. One particular -module deserves some attention: :mod:`sys` (XXX reference: ../lib/module- -sys.html), which is built into every Python interpreter. The variables +document, the Python Library Reference ("Library Reference" hereafter). Some +modules are built into the interpreter; these provide access to operations that +are not part of the core of the language but are nevertheless built in, either +for efficiency or to provide access to operating system primitives such as +system calls. The set of such modules is a configuration option which also +depends on the underlying platform For example, the :mod:`winreg` module is only +provided on Windows systems. One particular module deserves some attention: +:mod:`sys`, which is built into every Python interpreter. The variables ``sys.ps1`` and ``sys.ps2`` define the strings used as primary and secondary prompts: Modified: doctools/trunk/Doc-26/tutorial/stdlib.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/stdlib.rst (original) +++ doctools/trunk/Doc-26/tutorial/stdlib.rst Thu Aug 2 20:07:46 2007 @@ -10,8 +10,8 @@ Operating System Interface ========================== -The :mod:`os` (XXX reference: ../lib/module-os.html) module provides dozens of -functions for interacting with the operating system:: +The :mod:`os` module provides dozens of functions for interacting with the +operating system:: >>> import os >>> os.system('time 0:02') @@ -35,9 +35,8 @@ >>> help(os) <returns an extensive manual page created from the module's docstrings> -For daily file and directory management tasks, the :mod:`shutil` (XXX -reference: ../lib/module-shutil.html) module provides a higher level interface -that is easier to use:: +For daily file and directory management tasks, the :mod:`shutil` module provides +a higher level interface that is easier to use:: >>> import shutil >>> shutil.copyfile('data.db', 'archive.db') @@ -49,8 +48,8 @@ File Wildcards ============== -The :mod:`glob` (XXX reference: ../lib/module-glob.html) module provides a -function for making file lists from directory wildcard searches:: +The :mod:`glob` module provides a function for making file lists from directory +wildcard searches:: >>> import glob >>> glob.glob('*.py') @@ -63,18 +62,17 @@ ====================== Common utility scripts often need to process command line arguments. These -arguments are stored in the :mod:`sys` (XXX reference: ../lib/module-sys.html) -module's *argv* attribute as a list. For instance the following output results -from running ``python demo.py one two three`` at the command line:: +arguments are stored in the :mod:`sys` module's *argv* attribute as a list. For +instance the following output results from running ``python demo.py one two +three`` at the command line:: >>> import sys >>> print sys.argv ['demo.py', 'one', 'two', 'three'] -The :mod:`getopt` (XXX reference: ../lib/module-getopt.html) module processes -*sys.argv* using the conventions of the Unix :func:`getopt` function. More -powerful and flexible command line processing is provided by the :mod:`optparse` -(XXX reference: ../lib/module-optparse.html) module. +The :mod:`getopt` module processes *sys.argv* using the conventions of the Unix +:func:`getopt` function. More powerful and flexible command line processing is +provided by the :mod:`optparse` module. .. _tut-stderr: @@ -82,10 +80,9 @@ Error Output Redirection and Program Termination ================================================ -The :mod:`sys` (XXX reference: ../lib/module-sys.html) module also has -attributes for *stdin*, *stdout*, and *stderr*. The latter is useful for -emitting warnings and error messages to make them visible even when *stdout* has -been redirected:: +The :mod:`sys` module also has attributes for *stdin*, *stdout*, and *stderr*. +The latter is useful for emitting warnings and error messages to make them +visible even when *stdout* has been redirected:: >>> sys.stderr.write('Warning, log file not found starting a new one\n') Warning, log file not found starting a new one @@ -98,9 +95,9 @@ String Pattern Matching ======================= -The :mod:`re` (XXX reference: ../lib/module-re.html) module provides regular -expression tools for advanced string processing. For complex matching and -manipulation, regular expressions offer succinct, optimized solutions:: +The :mod:`re` module provides regular expression tools for advanced string +processing. For complex matching and manipulation, regular expressions offer +succinct, optimized solutions:: >>> import re >>> re.findall(r'\bf[a-z]*', 'which foot or hand fell fastest') @@ -120,8 +117,8 @@ Mathematics =========== -The :mod:`math` (XXX reference: ../lib/module-math.html) module gives access to -the underlying C library functions for floating point math:: +The :mod:`math` module gives access to the underlying C library functions for +floating point math:: >>> import math >>> math.cos(math.pi / 4.0) @@ -129,8 +126,7 @@ >>> math.log(1024, 2) 10.0 -The :mod:`random` (XXX reference: ../lib/module-random.html) module provides -tools for making random selections:: +The :mod:`random` module provides tools for making random selections:: >>> import random >>> random.choice(['apple', 'pear', 'banana']) @@ -149,9 +145,8 @@ =============== There are a number of modules for accessing the internet and processing internet -protocols. Two of the simplest are :mod:`urllib2` (XXX reference: ../lib/module- -urllib2.html) for retrieving data from urls and :mod:`smtplib` (XXX reference: -../lib/module-smtplib.html) for sending mail:: +protocols. Two of the simplest are :mod:`urllib2` for retrieving data from urls +and :mod:`smtplib` for sending mail:: >>> import urllib2 >>> for line in urllib2.urlopen('http://tycho.usno.navy.mil/cgi-bin/timer.pl'): @@ -176,11 +171,11 @@ Dates and Times =============== -The :mod:`datetime` (XXX reference: ../lib/module-datetime.html) module supplies -classes for manipulating dates and times in both simple and complex ways. While -date and time arithmetic is supported, the focus of the implementation is on -efficient member extraction for output formatting and manipulation. The module -also supports objects that are timezone aware. :: +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 +focus of the implementation is on efficient member extraction for output +formatting and manipulation. The module also supports objects that are timezone +aware. :: # dates are easily constructed and formatted >>> from datetime import date @@ -203,10 +198,8 @@ ================ Common data archiving and compression formats are directly supported by modules -including: :mod:`zlib` (XXX reference: ../lib/module-zlib.html), :mod:`gzip` -(XXX reference: ../lib/module-gzip.html), :mod:`bz2` (XXX reference: ../lib -/module-bz2.html), :mod:`zipfile` (XXX reference: ../lib/module-zipfile.html), -and :mod:`tarfile` (XXX reference: ../lib/module-tarfile.html). :: +including: :mod:`zlib`, :mod:`gzip`, :mod:`bz2`, :mod:`zipfile` and +:mod:`tarfile`. :: >>> import zlib >>> s = 'witch which has which witches wrist watch' @@ -232,8 +225,7 @@ For example, it may be tempting to use the tuple packing and unpacking feature instead of the traditional approach to swapping arguments. The :mod:`timeit` -(XXX reference: ../lib/module-timeit.html) module quickly demonstrates a modest -performance advantage:: +module quickly demonstrates a modest performance advantage:: >>> from timeit import Timer >>> Timer('t=a; a=b; b=t', 'a=1; b=2').timeit() @@ -241,9 +233,9 @@ >>> Timer('a,b = b,a', 'a=1; b=2').timeit() 0.54962537085770791 -In contrast to :mod:`timeit`'s fine level of granularity, the :mod:`profile` -(XXX reference: ../lib/module-profile.html) and :mod:`pstats` modules provide -tools for identifying time critical sections in larger blocks of code. +In contrast to :mod:`timeit`'s fine level of granularity, the :mod:`profile` and +:mod:`pstats` modules provide tools for identifying time critical sections in +larger blocks of code. .. _tut-quality-control: @@ -255,12 +247,12 @@ function as it is developed and to run those tests frequently during the development process. -The :mod:`doctest` (XXX reference: ../lib/module-doctest.html) module provides a -tool for scanning a module and validating tests embedded in a program's -docstrings. Test construction is as simple as cutting-and-pasting a typical -call along with its results into the docstring. This improves the documentation -by providing the user with an example and it allows the doctest module to make -sure the code remains true to the documentation:: +The :mod:`doctest` module provides a tool for scanning a module and validating +tests embedded in a program's docstrings. Test construction is as simple as +cutting-and-pasting a typical call along with its results into the docstring. +This improves the documentation by providing the user with an example and it +allows the doctest module to make sure the code remains true to the +documentation:: def average(values): """Computes the arithmetic mean of a list of numbers. @@ -273,9 +265,9 @@ import doctest doctest.testmod() # automatically validate the embedded tests -The :mod:`unittest` (XXX reference: ../lib/module-unittest.html) module is not -as effortless as the :mod:`doctest` module, but it allows a more comprehensive -set of tests to be maintained in a separate file:: +The :mod:`unittest` module is not as effortless as the :mod:`doctest` module, +but it allows a more comprehensive set of tests to be maintained in a separate +file:: import unittest @@ -298,28 +290,24 @@ Python has a "batteries included" philosophy. This is best seen through the sophisticated and robust capabilities of its larger packages. For example: -* The :mod:`xmlrpclib` (XXX reference: ../lib/module-xmlrpclib.html) and - :mod:`SimpleXMLRPCServer` (XXX reference: ../lib/module-SimpleXMLRPCServer.html) - modules make implementing remote procedure calls into an almost trivial task. - Despite the modules names, no direct knowledge or handling of XML is needed. - -* The :mod:`email` (XXX reference: ../lib/module-email.html) package is a - library for managing email messages, including MIME and other RFC 2822-based - message documents. Unlike :mod:`smtplib` and :mod:`poplib` which actually send - and receive messages, the email package has a complete toolset for building or - decoding complex message structures (including attachments) and for implementing - internet encoding and header protocols. - -* The :mod:`xml.dom` (XXX reference: ../lib/module-xml.dom.html) and - :mod:`xml.sax` (XXX reference: ../lib/module-xml.sax.html) packages provide - robust support for parsing this popular data interchange format. Likewise, the - :mod:`csv` (XXX reference: ../lib/module-csv.html) module supports direct reads - and writes in a common database format. Together, these modules and packages - greatly simplify data interchange between python applications and other tools. +* The :mod:`xmlrpclib` and :mod:`SimpleXMLRPCServer` modules make implementing + remote procedure calls into an almost trivial task. Despite the modules + names, no direct knowledge or handling of XML is needed. + +* The :mod:`email` package is a library for managing email messages, including + MIME and other RFC 2822-based message documents. Unlike :mod:`smtplib` and + :mod:`poplib` which actually send and receive messages, the email package has + a complete toolset for building or decoding complex message structures + (including attachments) and for implementing internet encoding and header + protocols. + +* The :mod:`xml.dom` and :mod:`xml.sax` packages provide robust support for + parsing this popular data interchange format. Likewise, the :mod:`csv` module + supports direct reads and writes in a common database format. Together, these + modules and packages greatly simplify data interchange between python + applications and other tools. * Internationalization is supported by a number of modules including - :mod:`gettext` (XXX reference: ../lib/module-gettext.html), :mod:`locale` (XXX - reference: ../lib/module-locale.html), and the :mod:`codecs` (XXX reference: - ../lib/module-codecs.html) package. + :mod:`gettext`, :mod:`locale`, and the :mod:`codecs` package. Modified: doctools/trunk/Doc-26/tutorial/stdlib2.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/stdlib2.rst (original) +++ doctools/trunk/Doc-26/tutorial/stdlib2.rst Thu Aug 2 20:07:46 2007 @@ -13,19 +13,17 @@ Output Formatting ================= -The :mod:`repr` (XXX reference: ../lib/module-repr.html) module provides a -version of :func:`repr` customized for abbreviated displays of large or deeply -nested containers:: +The :mod:`repr` module provides a version of :func:`repr` customized for +abbreviated displays of large or deeply nested containers:: >>> import repr >>> repr.repr(set('supercalifragilisticexpialidocious')) "set(['a', 'c', 'd', 'e', 'f', 'g', ...])" -The :mod:`pprint` (XXX reference: ../lib/module-pprint.html) module offers more -sophisticated control over printing both built-in and user defined objects in a -way that is readable by the interpreter. When the result is longer than one -line, the "pretty printer" adds line breaks and indentation to more clearly -reveal data structure:: +The :mod:`pprint` module offers more sophisticated control over printing both +built-in and user defined objects in a way that is readable by the interpreter. +When the result is longer than one line, the "pretty printer" adds line breaks +and indentation to more clearly reveal data structure:: >>> import pprint >>> t = [[[['black', 'cyan'], 'white', ['green', 'red']], [['magenta', @@ -38,8 +36,8 @@ [['magenta', 'yellow'], 'blue']]] -The :mod:`textwrap` (XXX reference: ../lib/module-textwrap.html) module formats -paragraphs of text to fit a given screen width:: +The :mod:`textwrap` module formats paragraphs of text to fit a given screen +width:: >>> import textwrap >>> doc = """The wrap() method is just like fill() except that it returns @@ -52,10 +50,9 @@ instead of one big string with newlines to separate the wrapped lines. -The :mod:`locale` (XXX reference: ../lib/module-locale.html) module accesses a -database of culture specific data formats. The grouping attribute of locale's -format function provides a direct way of formatting numbers with group -separators:: +The :mod:`locale` module accesses a database of culture specific data formats. +The grouping attribute of locale's format function provides a direct way of +formatting numbers with group separators:: >>> import locale >>> locale.setlocale(locale.LC_ALL, 'English_United States.1252') @@ -74,10 +71,9 @@ Templating ========== -The :mod:`string` (XXX reference: ../lib/module-string.html) module includes a -versatile :class:`Template` class with a simplified syntax suitable for editing -by end-users. This allows users to customize their applications without having -to alter the application. +The :mod:`string` module includes a versatile :class:`Template` class with a +simplified syntax suitable for editing by end-users. This allows users to +customize their applications without having to alter the application. The format uses placeholder names formed by ``$`` with valid Python identifiers (alphanumeric characters and underscores). Surrounding the placeholder with @@ -136,11 +132,10 @@ Working with Binary Data Record Layouts ======================================= -The :mod:`struct` (XXX reference: ../lib/module-struct.html) module provides -:func:`pack` and :func:`unpack` functions for working with variable length -binary record formats. The following example shows how to loop through header -information in a ZIP file (with pack codes ``"H"`` and ``"L"`` representing two -and four byte unsigned numbers respectively):: +The :mod:`struct` module provides :func:`pack` and :func:`unpack` functions for +working with variable length binary record formats. The following example shows +how to loop through header information in a ZIP file (with pack codes ``"H"`` +and ``"L"`` representing two and four byte unsigned numbers respectively):: import struct @@ -170,9 +165,8 @@ that accept user input while other tasks run in the background. A related use case is running I/O in parallel with computations in another thread. -The following code shows how the high level :mod:`threading` (XXX reference: -../lib/module-threading.html) module can run tasks in background while the main -program continues to run:: +The following code shows how the high level :mod:`threading` module can run +tasks in background while the main program continues to run:: import threading, zipfile @@ -202,10 +196,9 @@ While those tools are powerful, minor design errors can result in problems that are difficult to reproduce. So, the preferred approach to task coordination is to concentrate all access to a resource in a single thread and then use the -:mod:`Queue` (XXX reference: ../lib/module-Queue.html) module to feed that -thread with requests from other threads. Applications using :class:`Queue` -objects for inter-thread communication and coordination are easier to design, -more readable, and more reliable. +:mod:`Queue` module to feed that thread with requests from other threads. +Applications using :class:`Queue` objects for inter-thread communication and +coordination are easier to design, more readable, and more reliable. .. _tut-logging: @@ -213,9 +206,8 @@ Logging ======= -The :mod:`logging` (XXX reference: ../lib/module-logging.html) module offers a -full featured and flexible logging system. At its simplest, log messages are -sent to a file or to ``sys.stderr``:: +The :mod:`logging` module offers a full featured and flexible logging system. +At its simplest, log messages are sent to a file or to ``sys.stderr``:: import logging logging.debug('Debugging information') @@ -253,11 +245,10 @@ This approach works fine for most applications but occasionally there is a need to track objects only as long as they are being used by something else. Unfortunately, just tracking them creates a reference that makes them permanent. -The :mod:`weakref` (XXX reference: ../lib/module-weakref.html) module provides -tools for tracking objects without creating a reference. When the object is no -longer needed, it is automatically removed from a weakref table and a callback -is triggered for weakref objects. Typical applications include caching objects -that are expensive to create:: +The :mod:`weakref` module provides tools for tracking objects without creating a +reference. When the object is no longer needed, it is automatically removed +from a weakref table and a callback is triggered for weakref objects. Typical +applications include caching objects that are expensive to create:: >>> import weakref, gc >>> class A: @@ -292,11 +283,11 @@ sometimes there is a need for alternative implementations with different performance trade-offs. -The :mod:`array` (XXX reference: ../lib/module-array.html) module provides an -:class:`array()` object that is like a list that stores only homogenous data and -stores it more compactly. The following example shows an array of numbers -stored as two byte unsigned binary numbers (typecode ``"H"``) rather than the -usual 16 bytes per entry for regular lists of python int objects:: +The :mod:`array` module provides an :class:`array()` object that is like a list +that stores only homogenous data and stores it more compactly. The following +example shows an array of numbers stored as two byte unsigned binary numbers +(typecode ``"H"``) rather than the usual 16 bytes per entry for regular lists of +python int objects:: >>> from array import array >>> a = array('H', [4000, 10, 700, 22222]) @@ -305,10 +296,10 @@ >>> a[1:3] array('H', [10, 700]) -The :mod:`collections` (XXX reference: ../lib/module-collections.html) module -provides a :class:`deque()` object that is like a list with faster appends and -pops from the left side but slower lookups in the middle. These objects are well -suited for implementing queues and breadth first tree searches:: +The :mod:`collections` module provides a :class:`deque()` object that is like a +list with faster appends and pops from the left side but slower lookups in the +middle. These objects are well suited for implementing queues and breadth first +tree searches:: >>> from collections import deque >>> d = deque(["task1", "task2", "task3"]) @@ -325,8 +316,8 @@ unsearched.append(m) In addition to alternative list implementations, the library also offers other -tools such as the :mod:`bisect` (XXX reference: ../lib/module-bisect.html) -module with functions for manipulating sorted lists:: +tools such as the :mod:`bisect` module with functions for manipulating sorted +lists:: >>> import bisect >>> scores = [(100, 'perl'), (200, 'tcl'), (400, 'lua'), (500, 'python')] @@ -334,10 +325,10 @@ >>> scores [(100, 'perl'), (200, 'tcl'), (300, 'ruby'), (400, 'lua'), (500, 'python')] -The :mod:`heapq` (XXX reference: ../lib/module-heapq.html) module provides -functions for implementing heaps based on regular lists. The lowest valued -entry is always kept at position zero. This is useful for applications which -repeatedly access the smallest element but do not want to run a full list sort:: +The :mod:`heapq` module provides functions for implementing heaps based on +regular lists. The lowest valued entry is always kept at position zero. This +is useful for applications which repeatedly access the smallest element but do +not want to run a full list sort:: >>> from heapq import heapify, heappop, heappush >>> data = [1, 3, 5, 7, 9, 2, 4, 6, 8, 0] @@ -352,14 +343,14 @@ Decimal Floating Point Arithmetic ================================= -The :mod:`decimal` (XXX reference: ../lib/module-decimal.html) module offers a -:class:`Decimal` datatype for decimal floating point arithmetic. Compared to -the built-in :class:`float` implementation of binary floating point, the new -class is especially helpful for financial applications and other uses which -require exact decimal representation, control over precision, control over -rounding to meet legal or regulatory requirements, tracking of significant -decimal places, or for applications where the user expects the results to match -calculations done by hand. +The :mod:`decimal` module offers a :class:`Decimal` datatype for decimal +floating point arithmetic. Compared to the built-in :class:`float` +implementation of binary floating point, the new class is especially helpful for +financial applications and other uses which require exact decimal +representation, control over precision, control over rounding to meet legal or +regulatory requirements, tracking of significant decimal places, or for +applications where the user expects the results to match calculations done by +hand. For example, calculating a 5% tax on a 70 cent phone charge gives different results in decimal floating point and binary floating point. The difference Modified: doctools/trunk/Doc-26/tutorial/whatnow.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/whatnow.rst (original) +++ doctools/trunk/Doc-26/tutorial/whatnow.rst Thu Aug 2 20:07:46 2007 @@ -11,7 +11,7 @@ This tutorial is part of Python's documentation set. Some other documents in the set are: -* Python Library Reference (XXX reference: ../lib/lib.html): +* :ref:`library-index`: You should browse through this manual, which gives complete (though terse) reference material about types, functions, and the modules in the standard @@ -21,12 +21,12 @@ and many other tasks. Skimming through the Library Reference will give you an idea of what's available. -* Installing Python Modules (XXX reference: ../inst/inst.html) explains how to - install external modules written by other Python users. +* :ref:`install-index` explains how to install external modules written by other + Python users. -* Language Reference (XXX reference: ../ref/ref.html): A detailed explanation - of Python's syntax and semantics. It's heavy reading, but is useful as a - complete guide to the language itself. +* :ref:`reference-index`: A detailed explanation of Python's syntax and + semantics. It's heavy reading, but is useful as a complete guide to the + language itself. More Python resources: Modified: doctools/trunk/Doc-26/whatsnew/2.3.rst ============================================================================== --- doctools/trunk/Doc-26/whatsnew/2.3.rst (original) +++ doctools/trunk/Doc-26/whatsnew/2.3.rst Thu Aug 2 20:07:46 2007 @@ -30,10 +30,9 @@ This article doesn't attempt to provide a complete specification of the new features, but instead provides a convenient overview. For full details, you should refer to the documentation for Python 2.3, such as the Python Library -Reference (XXX reference: ../lib/lib.html) and the Python Reference Manual (XXX -reference: ../ref/ref.html). If you want to understand the complete -implementation and design rationale, refer to the PEP for a particular new -feature. +Reference and the Python Reference Manual. If you want to understand the +complete implementation and design rationale, refer to the PEP for a particular +new feature. .. % ====================================================================== @@ -1345,7 +1344,7 @@ elements in the iterator for which the function :func:`predicate` returns :const:`True`, and ``itertools.repeat(obj, N)`` returns ``obj`` *N* times. There are a number of other functions in the module; see the package's reference - documentation (XXX reference: ../lib/module-itertools.html) for details. + documentation for details. (Contributed by Raymond Hettinger.) * Two new functions in the :mod:`math` module, :func:`degrees(rads)` and @@ -1506,8 +1505,7 @@ the text wrapping strategy. Both the :class:`TextWrapper` class and the :func:`wrap` and :func:`fill` functions support a number of additional keyword arguments for fine-tuning the formatting; consult the module's documentation - (XXX reference: ../lib/module-textwrap.html) for details. (Contributed by Greg - Ward.) + for details. (Contributed by Greg Ward.) * The :mod:`thread` and :mod:`threading` modules now have companion modules, :mod:`dummy_thread` and :mod:`dummy_threading`, that provide a do-nothing @@ -1725,8 +1723,8 @@ support for parsing strings and getting back a :class:`date` or :class:`datetime`. -For more information, refer to the module's reference documentation (XXX -reference: ../lib/module-datetime.html). (Contributed by Tim Peters.) +For more information, refer to the module's reference documentation. +(Contributed by Tim Peters.) .. % ====================================================================== @@ -1787,10 +1785,8 @@ set maximum length of output $ -See the module's documentation (XXX reference: ../lib/module-optparse.html) for -more details. +See the module's documentation for more details. -.. % $ prevent Emacs tex-mode from getting confused Optik was written by Greg Ward, with suggestions from the readers of the Getopt SIG. Modified: doctools/trunk/Doc-26/whatsnew/2.4.rst ============================================================================== --- doctools/trunk/Doc-26/whatsnew/2.4.rst (original) +++ doctools/trunk/Doc-26/whatsnew/2.4.rst Thu Aug 2 20:07:46 2007 @@ -25,10 +25,9 @@ This article doesn't attempt to provide a complete specification of every single new feature, but instead provides a brief introduction to each feature. For full details, you should refer to the documentation for Python 2.4, such as the -Python Library Reference (XXX reference: ../lib/lib.html) and the Python -Reference Manual (XXX reference: ../ref/ref.html). Often you will be referred -to the PEP for a particular new feature for explanations of the implementation -and design rationale. +Python Library Reference and the Python Reference Manual. Often you will be +referred to the PEP for a particular new feature for explanations of the +implementation and design rationale. .. % ====================================================================== Modified: doctools/trunk/Doc-26/whatsnew/2.6.rst ============================================================================== --- doctools/trunk/Doc-26/whatsnew/2.6.rst (original) +++ doctools/trunk/Doc-26/whatsnew/2.6.rst Thu Aug 2 20:07:46 2007 @@ -3,8 +3,8 @@ **************************** :Author: A.M. Kuchling - -.. |release| replace:: 0.0 +:Release: |release| +:Date: |today| .. % $Id: whatsnew26.tex 55746 2007-06-02 18:33:53Z neal.norwitz $ .. % Rules for maintenance: Modified: doctools/trunk/Doc-3k/TODO ============================================================================== --- doctools/trunk/Doc-3k/TODO (original) +++ doctools/trunk/Doc-3k/TODO Thu Aug 2 20:07:46 2007 @@ -1,7 +1,6 @@ To do after conversion ====================== -* fix all references and links marked with `XXX` * split very large files and add toctrees * integrate standalone HOWTOs * find out which files get "comments disabled" metadata Modified: doctools/trunk/Doc-3k/about.rst ============================================================================== --- doctools/trunk/Doc-3k/about.rst (original) +++ doctools/trunk/Doc-3k/about.rst Thu Aug 2 20:07:46 2007 @@ -2,6 +2,7 @@ About these documents ===================== + These documents are generated from `reStructuredText <http://docutils.sf.net/rst.html>`_ sources by *Sphinx*, a document processor specifically written for the Python documentation. @@ -15,4 +16,6 @@ See :ref:`reporting-bugs` for information how to report bugs in Python itself. -.. include:: ACKS \ No newline at end of file +.. % include the ACKS file here so that it can be maintained separately + +.. include:: ACKS Modified: doctools/trunk/Doc-3k/c-api/concrete.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/concrete.rst (original) +++ doctools/trunk/Doc-3k/c-api/concrete.rst Thu Aug 2 20:07:46 2007 @@ -2318,22 +2318,19 @@ .. cfunction:: PyObject* PyDict_Items(PyObject *p) Return a :ctype:`PyListObject` containing all the items from the dictionary, as - in the dictionary method :meth:`items` (see the Python Library Reference (XXX - reference: ../lib/lib.html)). + in the dictionary method :meth:`dict.items`. .. cfunction:: PyObject* PyDict_Keys(PyObject *p) Return a :ctype:`PyListObject` containing all the keys from the dictionary, as - in the dictionary method :meth:`keys` (see the Python Library Reference (XXX - reference: ../lib/lib.html)). + in the dictionary method :meth:`dict.keys`. .. cfunction:: PyObject* PyDict_Values(PyObject *p) Return a :ctype:`PyListObject` containing all the values from the dictionary - *p*, as in the dictionary method :meth:`values` (see the Python Library - Reference (XXX reference: ../lib/lib.html)). + *p*, as in the dictionary method :meth:`dict.values`. .. cfunction:: Py_ssize_t PyDict_Size(PyObject *p) Modified: doctools/trunk/Doc-3k/c-api/intro.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/intro.rst (original) +++ doctools/trunk/Doc-3k/c-api/intro.rst Thu Aug 2 20:07:46 2007 @@ -99,12 +99,11 @@ deallocated, they are typically static :ctype:`PyTypeObject` objects. All Python objects (even Python integers) have a :dfn:`type` and a -:dfn:`reference count`. An object's type determines what kind of object it is -(e.g., an integer, a list, or a user-defined function; there are many more as -explained in the Python Reference Manual (XXX reference: ../ref/ref.html)). For -each of the well-known types there is a macro to check whether an object is of -that type; for instance, ``PyList_Check(a)`` is true if (and only if) the object -pointed to by *a* is a Python list. +:dfn:`reference count`. An object's type determines what kind of object it is +(e.g., an integer, a list, or a user-defined function; there are many more as +explained in :ref:`types`). For each of the well-known types there is a macro +to check whether an object is of that type; for instance, ``PyList_Check(a)`` is +true if (and only if) the object pointed to by *a* is a Python list. .. _api-refcounts: Modified: doctools/trunk/Doc-3k/c-api/newtypes.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/newtypes.rst (original) +++ doctools/trunk/Doc-3k/c-api/newtypes.rst Thu Aug 2 20:07:46 2007 @@ -610,17 +610,17 @@ This field is inherited by subtypes. -PyNumberMethods \*tp_as_number; +.. cmember:: PyNumberMethods *tp_as_number; -XXX + XXX -PySequenceMethods \*tp_as_sequence; +.. cmember:: PySequenceMethods *tp_as_sequence; -XXX + XXX -PyMappingMethods \*tp_as_mapping; +.. cmember:: PyMappingMethods *tp_as_mapping; -XXX + XXX .. cmember:: hashfunc PyTypeObject.tp_hash @@ -842,12 +842,13 @@ .. data:: Py_TPFLAGS_HAVE_GC - This bit is set when the object supports garbage collection. If this bit is - set, instances must be created using :cfunc:`PyObject_GC_New` and destroyed - using :cfunc:`PyObject_GC_Del`. More information in section XXX about garbage - collection. This bit also implies that the GC-related fields - :attr:`tp_traverse` and :attr:`tp_clear` are present in the type object; but - those fields also exist when :const:`Py_TPFLAGS_HAVE_GC` is clear but + This bit is set when the object supports garbage collection. If this bit + is set, instances must be created using :cfunc:`PyObject_GC_New` and + destroyed using :cfunc:`PyObject_GC_Del`. More information in section + :ref:`supporting-cycle-detection`. This bit also implies that the + GC-related fields :attr:`tp_traverse` and :attr:`tp_clear` are present in + the type object; but those fields also exist when + :const:`Py_TPFLAGS_HAVE_GC` is clear but :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` is set. @@ -1598,9 +1599,8 @@ other objects, or which only store references to atomic types (such as numbers or strings), do not need to provide any explicit support for garbage collection. -An example showing the use of these interfaces can be found in "Supporting the -Cycle Collector (XXX reference: ../ext/example-cycle-support.html)" in Extending -and Embedding the Python Interpreter (XXX reference: ../ext/ext.html). +.. An example showing the use of these interfaces can be found in "Supporting the +.. Cycle Collector (XXX reference: ../ext/example-cycle-support.html)". To create a container type, the :attr:`tp_flags` field of the type object must include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the Modified: doctools/trunk/Doc-3k/c-api/utilities.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/utilities.rst (original) +++ doctools/trunk/Doc-3k/c-api/utilities.rst Thu Aug 2 20:07:46 2007 @@ -366,6 +366,7 @@ .. versionchanged:: 2.4 *version* indicates the file format. + The following functions allow marshalled values to be read back in. XXX What about error detection? It appears that reading past the end of the @@ -421,8 +422,8 @@ ===================================== These functions are useful when creating your own extensions functions and -methods. Additional information and examples are available in Extending and -Embedding the Python Interpreter (XXX reference: ../ext/ext.html). +methods. Additional information and examples are available in +:ref:`extending-index`. The first three of these functions described, :cfunc:`PyArg_ParseTuple`, :cfunc:`PyArg_ParseTupleAndKeywords`, and :cfunc:`PyArg_Parse`, all use *format Modified: doctools/trunk/Doc-3k/distutils/index.rst ============================================================================== --- doctools/trunk/Doc-3k/distutils/index.rst (original) +++ doctools/trunk/Doc-3k/distutils/index.rst Thu Aug 2 20:07:46 2007 @@ -4,6 +4,8 @@ Distributing Python Modules ############################### +:Authors: Greg Ward, Anthony Baxter +:Email: distutils-sig(a)python.org :Release: |version| :Date: |today| Modified: doctools/trunk/Doc-3k/distutils/introduction.rst ============================================================================== --- doctools/trunk/Doc-3k/distutils/introduction.rst (original) +++ doctools/trunk/Doc-3k/distutils/introduction.rst Thu Aug 2 20:07:46 2007 @@ -6,8 +6,8 @@ This document covers using the Distutils to distribute your Python modules, concentrating on the role of developer/distributor: if you're looking for -information on installing Python modules, you should refer to the Installing -Python Modules (XXX reference: ../inst/inst.html) manual. +information on installing Python modules, you should refer to the +:ref:`install-index` chapter. .. _distutils-concepts: Modified: doctools/trunk/Doc-3k/extending/building.rst ============================================================================== --- doctools/trunk/Doc-3k/extending/building.rst (original) +++ doctools/trunk/Doc-3k/extending/building.rst Thu Aug 2 20:07:46 2007 @@ -52,7 +52,7 @@ information to build packages, and it specifies the contents of the package. Normally, a package will contain of addition modules, like Python source modules, documentation, subpackages, etc. Please refer to the distutils -documentation in Distributing Python Modules (XXX reference: ../dist/dist.html) +documentation in :ref:`distutils-index` to learn more about the features of distutils; this section explains building extension modules only. Modified: doctools/trunk/Doc-3k/extending/extending.rst ============================================================================== --- doctools/trunk/Doc-3k/extending/extending.rst (original) +++ doctools/trunk/Doc-3k/extending/extending.rst Thu Aug 2 20:07:46 2007 @@ -115,10 +115,9 @@ second global variable stores the "associated value" of the exception (the second argument to :keyword:`raise`). A third variable contains the stack traceback in case the error originated in Python code. These three variables -are the C equivalents of the result in Python of :meth:`sys.exc_info` (see the -section on module :mod:`sys` in the Python Library Reference (XXX reference: -../lib/lib.html)). It is important to know about them to understand how errors -are passed around. +are the C equivalents of the result in Python of :meth:`sys.exc_info` (see the +section on module :mod:`sys` in the Python Library Reference). It is important +to know about them to understand how errors are passed around. The Python API defines a number of functions to set various types of exceptions. @@ -212,8 +211,7 @@ Note that the Python name for the exception object is :exc:`spam.error`. The :cfunc:`PyErr_NewException` function may create a class with the base class being :exc:`Exception` (unless another class is passed in instead of *NULL*), -described in the Python Library Reference (XXX reference: ../lib/lib.html) under -"Built-in Exceptions." +described in :ref:`bltin-exceptions`. Note also that the :cdata:`SpamError` variable retains a reference to the newly created exception class; this is intentional! Since the exception could be @@ -546,10 +544,9 @@ The *arg* argument must be a tuple object containing an argument list passed from Python to a C function. The *format* argument must be a format string, -whose syntax is explained in "Parsing arguments and building values (XXX -reference: ../api/arg-parsing.html)" in the Python/C API Reference Manual (XXX -reference: ../api/api.html). The remaining arguments must be addresses of -variables whose type is determined by the format string. +whose syntax is explained in :ref:`arg-parsing` in the Python/C API Reference +Manual. The remaining arguments must be addresses of variables whose type is +determined by the format string. Note that while :cfunc:`PyArg_ParseTuple` checks that the Python arguments have the required types, it cannot check the validity of the addresses of C variables @@ -814,7 +811,7 @@ The cycle detector is able to detect garbage cycles and can reclaim them so long as there are no finalizers implemented in Python (:meth:`__del__` methods). When there are such finalizers, the detector exposes the cycles through the -:mod:`gc` module (XXX reference: ../lib/module-gc.html) (specifically, the +:mod:`gc` module (specifically, the ``garbage`` variable in that module). The :mod:`gc` module also exposes a way to run the detector (the :func:`collect` function), as well as configuration interfaces and the ability to disable the detector at runtime. The cycle @@ -1255,8 +1252,7 @@ Finally it should be mentioned that CObjects offer additional functionality, which is especially useful for memory allocation and deallocation of the pointer stored in a CObject. The details are described in the Python/C API Reference -Manual (XXX reference: ../api/api.html) in the section "CObjects (XXX reference: -../api/cObjects.html)" and in the implementation of CObjects (files +Manual in the section :ref:`cobjects` and in the implementation of CObjects (files :file:`Include/cobject.h` and :file:`Objects/cobject.c` in the Python source code distribution). Modified: doctools/trunk/Doc-3k/extending/newtypes.rst ============================================================================== --- doctools/trunk/Doc-3k/extending/newtypes.rst (original) +++ doctools/trunk/Doc-3k/extending/newtypes.rst Thu Aug 2 20:07:46 2007 @@ -1355,9 +1355,8 @@ ------------------------- Python supports a variety of *abstract* 'protocols;' the specific interfaces -provided to use these interfaces are documented in the Python/C API Reference -Manual (XXX reference: ../api/api.html) in the chapter "Abstract Objects Layer -(XXX reference: ../api/abstract.html)." +provided to use these interfaces are documented in :ref:`abstract`. + A number of these abstract interfaces were defined early in the development of the Python implementation. In particular, the number, mapping, and sequence Modified: doctools/trunk/Doc-3k/extending/windows.rst ============================================================================== --- doctools/trunk/Doc-3k/extending/windows.rst (original) +++ doctools/trunk/Doc-3k/extending/windows.rst Thu Aug 2 20:07:46 2007 @@ -36,13 +36,11 @@ =================== There are two approaches to building extension modules on Windows, just as there -are on Unix: use the :mod:`distutils` (XXX reference: ../lib/module- -distutils.html) package to control the build process, or do things manually. -The distutils approach works well for most extensions; documentation on using -:mod:`distutils` (XXX reference: ../lib/module-distutils.html) to build and -package extension modules is available in Distributing Python Modules (XXX -reference: ../dist/dist.html). This section describes the manual approach to -building Python extensions written in C or C++. +are on Unix: use the :mod:`distutils` package to control the build process, or +do things manually. The distutils approach works well for most extensions; +documentation on using :mod:`distutils` to build and package extension modules +is available in :ref:`distutils-index`. This section describes the manual +approach to building Python extensions written in C or C++. To build extensions using these instructions, you need to have a copy of the Python sources of the same version as your installed Python. You will need Modified: doctools/trunk/Doc-3k/install/index.rst ============================================================================== --- doctools/trunk/Doc-3k/install/index.rst (original) +++ doctools/trunk/Doc-3k/install/index.rst Thu Aug 2 20:07:46 2007 @@ -1,12 +1,14 @@ -.. _install-index: - .. highlightlang:: none +.. _install-index: + ***************************** Installing Python Modules ***************************** :Author: Greg Ward +:Release: |version| +:Date: |today| .. % TODO: .. % Fill in XXX comments @@ -21,8 +23,6 @@ .. % Finally, it might be useful to include all the material from my "Care .. % and Feeding of a Python Installation" talk in here somewhere. Yow! -XXX: input{boilerplate} :XXX - .. topic:: Abstract This document describes the Python Distribution Utilities ("Distutils") from the @@ -30,17 +30,6 @@ standard Python installation by building and installing third-party Python modules and extensions. -.. % \begin{abstract} -.. % \noindent -.. % Abstract this! -.. % \end{abstract} - -.. % The ugly "%begin{latexonly}" pseudo-environment suppresses the table -.. % of contents for HTML generation. -.. % -.. % begin{latexonly} -.. % end{latexonly} - .. _inst-intro: @@ -64,7 +53,7 @@ document; there will be some brief forays into using Python's interactive mode to explore your installation, but that's it. If you're looking for information on how to distribute your own Python modules so that others may use them, see -the Distributing Python Modules (XXX reference: ../dist/dist.html) manual. +the :ref:`distutils-index` manual. .. _inst-trivial-install: @@ -728,7 +717,7 @@ (2) On Unix, if the :envvar:`HOME` environment variable is not defined, the user's home directory will be determined with the :func:`getpwuid` function from the - standard :mod:`pwd` (XXX reference: ../lib/module-pwd.html) module. + standard :mod:`pwd` module. (3) I.e., in the current directory (usually the location of the setup script). @@ -1020,4 +1009,3 @@ .. [#] Then you have no POSIX emulation available, but you also don't need :file:`cygwin1.dll`. - Modified: doctools/trunk/Doc-3k/library/array.rst ============================================================================== --- doctools/trunk/Doc-3k/library/array.rst (original) +++ doctools/trunk/Doc-3k/library/array.rst Thu Aug 2 20:07:46 2007 @@ -112,8 +112,7 @@ effectively make use of this information), it makes more sense to use the buffer interface supported by array objects. This method is maintained for backward compatibility and should be avoided in new code. The buffer interface is - documented in the Python/C API Reference Manual (XXX reference: - ../api/newTypes.html). + documented in :ref:`bufferobjects`. .. method:: array.byteswap() Modified: doctools/trunk/Doc-3k/library/audioop.rst ============================================================================== --- doctools/trunk/Doc-3k/library/audioop.rst (original) +++ doctools/trunk/Doc-3k/library/audioop.rst Thu Aug 2 20:07:46 2007 @@ -191,11 +191,7 @@ .. function:: rms(fragment, width) - Return the root-mean-square of the fragment, i.e. :: - - XXX: translate this math - \catcode`_=8 - \sqrt{\frac{\sum{{S_{i}}^{2}}}{n}} + Return the root-mean-square of the fragment, i.e. ``sqrt(sum(S_i^2)/n)``. This is a measure of the power in an audio signal. Modified: doctools/trunk/Doc-3k/library/codecs.rst ============================================================================== --- doctools/trunk/Doc-3k/library/codecs.rst (original) +++ doctools/trunk/Doc-3k/library/codecs.rst Thu Aug 2 20:07:46 2007 @@ -1157,11 +1157,7 @@ .. module:: encodings.idna :synopsis: Internationalized Domain Names implementation - - -.. % XXX The next line triggers a formatting bug, so it's commented out -.. % until that can be fixed. -.. % \moduleauthor{Martin v. L\"owis} +.. moduleauthor:: Martin v. Löwis .. versionadded:: 2.3 @@ -1220,13 +1216,10 @@ :mod:`encodings.utf_8_sig` --- UTF-8 codec with BOM signature ------------------------------------------------------------- -.. module:: encodings.utf-8-sig +.. module:: encodings.utf_8_sig :synopsis: UTF-8 codec with BOM signature .. moduleauthor:: Walter Dörwald - -.. % XXX utf_8_sig gives TeX errors - .. versionadded:: 2.5 This module implements a variant of the UTF-8 codec: On encoding a UTF-8 encoded Modified: doctools/trunk/Doc-3k/library/distutils.rst ============================================================================== --- doctools/trunk/Doc-3k/library/distutils.rst (original) +++ doctools/trunk/Doc-3k/library/distutils.rst Thu Aug 2 20:07:46 2007 @@ -13,23 +13,17 @@ 100%-pure Python, or may be extension modules written in C, or may be collections of Python packages which include modules coded in both Python and C. -This package is discussed in two separate documents which are included in the -Python documentation package. To learn about distributing new modules using the -:mod:`distutils` facilities, read Distributing Python Modules (XXX reference: -../dist/dist.html); this includes documentation needed to extend distutils. To -learn about installing Python modules, whether or not the author made use of the -:mod:`distutils` package, read Installing Python Modules (XXX reference: -../inst/inst.html). +This package is discussed in two separate chapters: .. seealso:: - `Distributing Python Modules <../dist/dist.html>`_ + :ref:`distutils-index` The manual for developers and packagers of Python modules. This describes how to prepare :mod:`distutils`\ -based packages so that they may be easily installed into an existing Python installation. - `Installing Python Modules <../inst/inst.html>`_ + :ref:`install-index` An "administrators" manual which includes information on installing modules into an existing Python installation. You do not need to be a Python programmer to read this manual. Modified: doctools/trunk/Doc-3k/library/exceptions.rst ============================================================================== --- doctools/trunk/Doc-3k/library/exceptions.rst (original) +++ doctools/trunk/Doc-3k/library/exceptions.rst Thu Aug 2 20:07:46 2007 @@ -1,3 +1,4 @@ +.. _bltin-exceptions: Built-in Exceptions =================== @@ -40,8 +41,8 @@ The built-in exception classes can be sub-classed to define new exceptions; programmers are encouraged to at least derive new exceptions from the :exc:`Exception` class and not :exc:`BaseException`. More information on -defining exceptions is available in the Python Tutorial (XXX reference: -../tut/tut.html) under the heading "User-defined Exceptions." +defining exceptions is available in the Python Tutorial under +:ref:`tut-userexceptions`. The following exceptions are only used as base classes for other exceptions. Modified: doctools/trunk/Doc-3k/library/functions.rst ============================================================================== --- doctools/trunk/Doc-3k/library/functions.rst (original) +++ doctools/trunk/Doc-3k/library/functions.rst Thu Aug 2 20:07:46 2007 @@ -154,8 +154,7 @@ def f(cls, arg1, arg2, ...): ... The ``@classmethod`` form is a function decorator -- see the description of - function definitions in chapter 7 of the Python Reference Manual (XXX reference: - ../ref/ref.html) for details. + function definitions in :ref:`function` for details. It can be called either on the class (such as ``C.f()``) or on an instance (such as ``C().f()``). The instance is ignored except for its class. If a class @@ -166,8 +165,7 @@ see :func:`staticmethod` in this section. For more information on class methods, consult the documentation on the standard - type hierarchy in chapter 3 of the Python Reference Manual (XXX reference: - ../ref/types.html) (at the bottom). + type hierarchy in :ref:`types`. .. versionadded:: 2.2 @@ -995,8 +993,7 @@ def f(arg1, arg2, ...): ... The ``@staticmethod`` form is a function decorator -- see the description of - function definitions in chapter 7 of the Python Reference Manual (XXX reference: - ../ref/function.html) for details. + function definitions in :ref:`function` for details. It can be called either on the class (such as ``C.f()``) or on an instance (such as ``C().f()``). The instance is ignored except for its class. @@ -1005,8 +1002,7 @@ advanced concept, see :func:`classmethod` in this section. For more information on static methods, consult the documentation on the - standard type hierarchy in chapter 3 of the Python Reference Manual (XXX - reference: ../ref/types.html) (at the bottom). + standard type hierarchy in :ref:`types`. .. versionadded:: 2.2 Modified: doctools/trunk/Doc-3k/library/objects.rst ============================================================================== --- doctools/trunk/Doc-3k/library/objects.rst (original) +++ doctools/trunk/Doc-3k/library/objects.rst Thu Aug 2 20:07:46 2007 @@ -22,8 +22,8 @@ in order of ascending priority (within a table) and grouping operators that have the same priority in the same box. Binary operators of the same priority group from left to right. (Unary operators group from right to left, but there you -have no real choice.) See chapter 5 of the Python Reference Manual (XXX -reference: ../ref/ref.html) for the complete picture on operator priorities. +have no real choice.) See :ref:`operator-summary` for the complete picture on +operator priorities. .. rubric:: Footnotes Modified: doctools/trunk/Doc-3k/library/operator.rst ============================================================================== --- doctools/trunk/Doc-3k/library/operator.rst (original) +++ doctools/trunk/Doc-3k/library/operator.rst Thu Aug 2 20:07:46 2007 @@ -36,13 +36,12 @@ __gt__(a, b) Perform "rich comparisons" between *a* and *b*. Specifically, ``lt(a, b)`` is - equivalent to ``a < b``, ``le(a, b)`` is equivalent to ``a <= b``, ``eq(a, b)`` - is equivalent to ``a == b``, ``ne(a, b)`` is equivalent to ``a != b``, ``gt(a, - b)`` is equivalent to ``a > b`` and ``ge(a, b)`` is equivalent to ``a >= b``. - Note that unlike the built-in :func:`cmp`, these functions can return any value, - which may or may not be interpretable as a Boolean value. See the Python - Reference Manual (XXX reference: ../ref/ref.html) for more information about - rich comparisons. + equivalent to ``a < b``, ``le(a, b)`` is equivalent to ``a <= b``, ``eq(a, + b)`` is equivalent to ``a == b``, ``ne(a, b)`` is equivalent to ``a != b``, + ``gt(a, b)`` is equivalent to ``a > b`` and ``ge(a, b)`` is equivalent to ``a + >= b``. Note that unlike the built-in :func:`cmp`, these functions can + return any value, which may or may not be interpretable as a Boolean value. + See :ref:`comparisons` for more information about rich comparisons. .. versionadded:: 2.2 Modified: doctools/trunk/Doc-3k/library/parser.rst ============================================================================== --- doctools/trunk/Doc-3k/library/parser.rst (original) +++ doctools/trunk/Doc-3k/library/parser.rst Thu Aug 2 20:07:46 2007 @@ -32,7 +32,7 @@ Most importantly, a good understanding of the Python grammar processed by the internal parser is required. For full information on the language syntax, refer -to the Python Language Reference (XXX reference: ../ref/ref.html). The parser +to :ref:`reference-index`. The parser itself is created from a grammar specification defined in the file :file:`Grammar/Grammar` in the standard Python distribution. The parse trees stored in the AST objects created by this module are the actual output from the Modified: doctools/trunk/Doc-3k/library/pdb.rst ============================================================================== --- doctools/trunk/Doc-3k/library/pdb.rst (original) +++ doctools/trunk/Doc-3k/library/pdb.rst Thu Aug 2 20:07:46 2007 @@ -405,6 +405,5 @@ Note that as an exception is propagated down the chain of callers, an ``'exception'`` event is generated at each level. -For more information on code and frame objects, refer to the Python Reference -Manual (XXX reference: ../ref/ref.html). +For more information on code and frame objects, refer to :ref:`types`. Modified: doctools/trunk/Doc-3k/library/stdtypes.rst ============================================================================== --- doctools/trunk/Doc-3k/library/stdtypes.rst (original) +++ doctools/trunk/Doc-3k/library/stdtypes.rst Thu Aug 2 20:07:46 2007 @@ -26,10 +26,7 @@ practically all objects can be compared, tested for truth value, and converted to a string (with the :func:`repr` function or the slightly different :func:`str` function). The latter function is implicitly used when an object is -written by the :keyword:`print` statement. (Information on the :keyword:`print` -statement (XXX reference: ../ref/print.html) and other language statements can -be found in the Python Reference Manual (XXX reference: ../ref/ref.html) and the -Python Tutorial (XXX reference: ../tut/tut.html).) +written by the :func:`print` function. .. _truth: @@ -178,10 +175,9 @@ .. index:: single: __cmp__() (instance method) -Instances of a class normally compare as non-equal unless the class defines the -:meth:`__cmp__` method. Refer to the Python Reference Manual (XXX reference: -../ref/customization.html) for information on the use of this method to effect -object comparisons. +Instances of a class normally compare as non-equal unless the class defines the +:meth:`__cmp__` method. Refer to :ref:`customization`) for information on the +use of this method to effect object comparisons. **Implementation note:** Objects of different types except numbers are ordered by their type names; objects of the same types that don't support proper @@ -490,12 +486,11 @@ object: list String literals are written in single or double quotes: ``'xyzzy'``, -``"frobozz"``. See chapter 2 of the Python Reference Manual (XXX reference: -../ref/strings.html) for more about string literals. Unicode strings are much -like strings, but are specified in the syntax using a preceding ``'u'`` -character: ``u'abc'``, ``u"def"``. Lists are constructed with square brackets, -separating items with commas: ``[a, b, c]``. Tuples are constructed by the -comma operator (not within square brackets), with or without enclosing +``"frobozz"``. See :ref:`strings` for more about string literals. Unicode +strings are much like strings, but are specified in the syntax using a preceding +``'u'`` character: ``u'abc'``, ``u"def"``. Lists are constructed with square +brackets, separating items with commas: ``[a, b, c]``. Tuples are constructed +by the comma operator (not within square brackets), with or without enclosing parentheses, but an empty tuple must have the enclosing parentheses, such as ``a, b, c`` or ``()``. A single item tuple must have a trailing comma, such as ``(d,)``. @@ -2106,8 +2101,7 @@ .. _classes and instances: -See chapters 3 and 7 of the Python Reference Manual (XXX reference: -../ref/ref.html) for these. +See :ref:`objects` and :ref:`class` for these. .. _typesfunctions: @@ -2122,8 +2116,7 @@ defined functions. Both support the same operation (to call the function), but the implementation is different, hence the different object types. -See the Python Reference Manual (XXX reference: ../ref/ref.html) for more -information. +See :ref:`function` for more information. .. _typesmethods: @@ -2165,8 +2158,7 @@ c = C() c.method.im_func.whoami = 'my name is c' -See the Python Reference Manual (XXX reference: ../ref/ref.html) for more -information. +See :ref:`types` for more information. .. _bltin-code-objects: @@ -2194,8 +2186,7 @@ A code object can be executed or evaluated by passing it (instead of a source string) to the :func:`exec` or :func:`eval` built-in functions. -See the Python Reference Manual (XXX reference: ../ref/ref.html) for more -information. +See :ref:`types` for more information. .. _bltin-type-objects: @@ -2232,9 +2223,9 @@ The Ellipsis Object ------------------- -This object is mostly used by extended slice notation (see the Python Reference -Manual (XXX reference: ../ref/ref.html)). It supports no special operations. -There is exactly one ellipsis object, named :const:`Ellipsis` (a built-in name). +This object is mostly used by extended slice notation (see :ref:`slicings`). It +supports no special operations. There is exactly one ellipsis object, named +:const:`Ellipsis` (a built-in name). It is written as ``Ellipsis`` or ``...``. @@ -2263,9 +2254,8 @@ Internal Objects ---------------- -See the Python Reference Manual (XXX reference: ../ref/ref.html) for this -information. It describes stack frame objects, traceback objects, and slice -objects. +See :ref:`types` for this information. It describes stack frame objects, +traceback objects, and slice objects. .. _specialattrs: @@ -2315,8 +2305,8 @@ .. rubric:: Footnotes -.. [#] Additional information on these special methods may be found in the Python - Reference Manual (XXX reference: ../ref/ref.html). +.. [#] Additional information on these special methods may be found in the Python + Reference Manual (:ref:`customization`). .. [#] As a consequence, the list ``[1, 2]`` is considered equal to ``[1.0, 2.0]``, and similarly for tuples. Modified: doctools/trunk/Doc-3k/library/warnings.rst ============================================================================== --- doctools/trunk/Doc-3k/library/warnings.rst (original) +++ doctools/trunk/Doc-3k/library/warnings.rst Thu Aug 2 20:07:46 2007 @@ -16,8 +16,8 @@ might want to issue a warning when a program uses an obsolete module. Python programmers issue warnings by calling the :func:`warn` function defined -in this module. (C programmers use :cfunc:`PyErr_Warn`; see the Python/C API -Reference Manual (XXX reference: ../api/exceptionHandling.html) for details). +in this module. (C programmers use :cfunc:`PyErr_Warn`; see +:ref:`exceptionhandling` for details). Warning messages are normally written to ``sys.stderr``, but their disposition can be changed flexibly, from ignoring all warnings to turning them into Modified: doctools/trunk/Doc-3k/library/weakref.rst ============================================================================== --- doctools/trunk/Doc-3k/library/weakref.rst (original) +++ doctools/trunk/Doc-3k/library/weakref.rst Thu Aug 2 20:07:46 2007 @@ -65,14 +65,8 @@ obj = Dict(red=1, green=2, blue=3) # this object is weak referencable -Extension types can easily be made to support weak references; see "Weak -Reference Support (XXX reference: ../ext/weakref-support.html)" in Extending and -Embedding the Python Interpreter (XXX reference: ../ext/ext.html). - -.. % The referenced section used to appear in this document with the -.. % \label weakref-extension. It would be good to be able to generate a -.. % redirect for the corresponding HTML page (weakref-extension.html) -.. % for on-line versions of this document. +Extension types can easily be made to support weak references; see +:ref:`weakref-support`. .. class:: ref(object[, callback]) Modified: doctools/trunk/Doc-3k/library/webbrowser.rst ============================================================================== --- doctools/trunk/Doc-3k/library/webbrowser.rst (original) +++ doctools/trunk/Doc-3k/library/webbrowser.rst Thu Aug 2 20:07:46 2007 @@ -151,9 +151,7 @@ Only on Windows platforms. (3) - Only on MacOS platforms; requires the standard MacPython :mod:`ic` module, - described in the Macintosh Library Modules (XXX reference: ../mac/module- - ic.html) manual. + Only on MacOS platforms; requires the standard MacPython :mod:`ic` module. (4) Only on MacOS X platform. Modified: doctools/trunk/Doc-3k/library/xml.etree.elementtree.rst ============================================================================== --- doctools/trunk/Doc-3k/library/xml.etree.elementtree.rst (original) +++ doctools/trunk/Doc-3k/library/xml.etree.elementtree.rst Thu Aug 2 20:07:46 2007 @@ -267,7 +267,7 @@ .. method:: Element.remove(subelement) - Removes *subelement* from the element. Unlike the findXXX methods this method + Removes *subelement* from the element. Unlike the findXYZ methods this method compares elements based on the instance identity, not on tag value or contents. Element objects also support the following sequence type methods for working Modified: doctools/trunk/Doc-3k/library/xml.sax.handler.rst ============================================================================== --- doctools/trunk/Doc-3k/library/xml.sax.handler.rst (original) +++ doctools/trunk/Doc-3k/library/xml.sax.handler.rst Thu Aug 2 20:07:46 2007 @@ -207,7 +207,7 @@ information to the application to expand prefixes in those contexts itself, if necessary. - .. % % XXX This is not really the default, is it? MvL + .. % XXX This is not really the default, is it? MvL Note that :meth:`startPrefixMapping` and :meth:`endPrefixMapping` events are not guaranteed to be properly nested relative to each-other: all @@ -232,7 +232,7 @@ The *name* parameter contains the raw XML 1.0 name of the element type as a string and the *attrs* parameter holds an object of the :class:`Attributes` - interface (XXX reference: attributes-objects.html) containing the attributes of + interface (see :ref:`attributes-objects`) containing the attributes of the element. The object passed as *attrs* may be re-used by the parser; holding on to a reference to it is not a reliable way to keep a copy of the attributes. To keep a copy of the attributes, use the :meth:`copy` method of the *attrs* @@ -254,7 +254,7 @@ The *name* parameter contains the name of the element type as a ``(uri, localname)`` tuple, the *qname* parameter contains the raw XML 1.0 name used in the source document, and the *attrs* parameter holds an instance of the - :class:`AttributesNS` interface (XXX reference: attributes-ns-objects.html) + :class:`AttributesNS` interface (see :ref:`attributes-ns-objects`) containing the attributes of the element. If no namespace is associated with the element, the *uri* component of *name* will be ``None``. The object passed as *attrs* may be re-used by the parser; holding on to a reference to it is not Modified: doctools/trunk/Doc-3k/maclib/mac.rst ============================================================================== --- doctools/trunk/Doc-3k/maclib/mac.rst (original) +++ doctools/trunk/Doc-3k/maclib/mac.rst Thu Aug 2 20:07:46 2007 @@ -11,8 +11,8 @@ This module is the Mac OS 9 (and earlier) implementation of the :mod:`os.path` module. It can be used to manipulate old-style Macintosh pathnames on Mac OS X -(or any other platform). Refer to the Python Library Reference (XXX reference: -../lib/lib.html) for documentation of :mod:`os.path`. +(or any other platform). Refer to the Python Library Reference for documentation +of :mod:`os.path`. The following functions are available in this module: :func:`normcase`, :func:`normpath`, :func:`isabs`, :func:`join`, :func:`split`, :func:`isdir`, Modified: doctools/trunk/Doc-3k/reference/datamodel.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/datamodel.rst (original) +++ doctools/trunk/Doc-3k/reference/datamodel.rst Thu Aug 2 20:07:46 2007 @@ -60,8 +60,8 @@ reference-counting scheme with (optional) delayed detection of cyclically linked garbage, which collects most objects as soon as they become unreachable, but is not guaranteed to collect garbage containing circular references. See the -Python Library Reference (XXX reference: ../lib/module-gc.html) for information -on controlling the collection of cyclic garbage.) +documentation of the :mod:`gc` module for information on controlling the +collection of cyclic garbage.) Note that the use of the implementation's tracing or debugging facilities may keep objects alive that would normally be collectable. Also note that catching @@ -865,12 +865,12 @@ single: stderr (in module sys) A file object represents an open file. File objects are created by the - :func:`open` built-in function, and also by :func:`os.popen`, :func:`os.fdopen`, - and the :meth:`makefile` method of socket objects (and perhaps by other - functions or methods provided by extension modules). The objects ``sys.stdin``, - ``sys.stdout`` and ``sys.stderr`` are initialized to file objects corresponding - to the interpreter's standard input, output and error streams. See the Python - Library Reference (XXX reference: ../lib/lib.html) for complete documentation of + :func:`open` built-in function, and also by :func:`os.popen`, + :func:`os.fdopen`, and the :meth:`makefile` method of socket objects (and + perhaps by other functions or methods provided by extension modules). The + objects ``sys.stdin``, ``sys.stdout`` and ``sys.stderr`` are initialized to + file objects corresponding to the interpreter's standard input, output and + error streams. See :ref:`bltin-file-objects` for complete documentation of file objects. Internal types @@ -1215,24 +1215,25 @@ .. note:: - ``del x`` doesn't directly call ``x.__del__()`` --- the former decrements the - reference count for ``x`` by one, and the latter is only called when ``x``'s - reference count reaches zero. Some common situations that may prevent the - reference count of an object from going to zero include: circular references - between objects (e.g., a doubly-linked list or a tree data structure with parent - and child pointers); a reference to the object on the stack frame of a function - that caught an exception (the traceback stored in ``sys.exc_info()[2]`` keeps - the stack frame alive); or a reference to the object on the stack frame that - raised an unhandled exception in interactive mode (the traceback stored in - ``sys.last_traceback`` keeps the stack frame alive). The first situation can - only be remedied by explicitly breaking the cycles; the latter two situations - can be resolved by storing ``None`` in ``sys.last_traceback``. Circular - references which are garbage are detected when the option cycle detector is - enabled (it's on by default), but can only be cleaned up if there are no Python- - level :meth:`__del__` methods involved. Refer to the documentation for the - :mod:`gc` module (XXX reference: ../lib/module-gc.html) for more information - about how :meth:`__del__` methods are handled by the cycle detector, - particularly the description of the ``garbage`` value. + ``del x`` doesn't directly call ``x.__del__()`` --- the former decrements + the reference count for ``x`` by one, and the latter is only called when + ``x``'s reference count reaches zero. Some common situations that may + prevent the reference count of an object from going to zero include: + circular references between objects (e.g., a doubly-linked list or a tree + data structure with parent and child pointers); a reference to the object + on the stack frame of a function that caught an exception (the traceback + stored in ``sys.exc_info()[2]`` keeps the stack frame alive); or a + reference to the object on the stack frame that raised an unhandled + exception in interactive mode (the traceback stored in + ``sys.last_traceback`` keeps the stack frame alive). The first situation + can only be remedied by explicitly breaking the cycles; the latter two + situations can be resolved by storing ``None`` in ``sys.last_traceback``. + Circular references which are garbage are detected when the option cycle + detector is enabled (it's on by default), but can only be cleaned up if + there are no Python- level :meth:`__del__` methods involved. Refer to the + documentation for the :mod:`gc` module for more information about how + :meth:`__del__` methods are handled by the cycle detector, particularly + the description of the ``garbage`` value. .. warning:: @@ -1821,9 +1822,7 @@ should also be made available as the method :meth:`iterkeys`. Iterator objects also need to implement this method; they are required to return - themselves. For more information on iterator objects, see "Iterator Types (XXX - reference: ../lib/typeiter.html)" in the Python Library Reference (XXX - reference: ../lib/lib.html). + themselves. For more information on iterator objects, see :ref:`typeiter`. The membership test operators (:keyword:`in` and :keyword:`not in`) are normally implemented as an iteration through a sequence. However, container objects can @@ -2103,9 +2102,7 @@ Typical uses of context managers include saving and restoring various kinds of global state, locking and unlocking resources, closing opened files, etc. -For more information on context managers, see "Context Types (XXX reference: -../lib/typecontextmanager.html)" in the Python Library Reference (XXX reference: -../lib/lib.html). +For more information on context managers, see :ref:`typecontextmanager`. .. method:: context manager.__enter__(self) Modified: doctools/trunk/Doc-3k/reference/expressions.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/expressions.rst (original) +++ doctools/trunk/Doc-3k/reference/expressions.rst Thu Aug 2 20:07:46 2007 @@ -699,9 +699,8 @@ object: method object: function - The result is up to the interpreter; see the Python Library Reference (XXX - reference: ../lib/built-in-funcs.html) for the descriptions of built-in - functions and methods. + The result is up to the interpreter; see :ref:`built-in-funcs` for the + descriptions of built-in functions and methods. a class object: .. index:: @@ -855,8 +854,7 @@ In addition to performing the modulo operation on numbers, the ``%`` operator is also overloaded by string and unicode objects to perform string formatting (also known as interpolation). The syntax for string formatting is described in the -Python Library Reference (XXX reference: ../lib/typesseq-strings.html), section -"Sequence Types". +Python Library Reference, section :ref:`typesseq-strings`. .. deprecated:: 2.3 The floor division operator, the modulo operator, and the :func:`divmod` @@ -1189,7 +1187,7 @@ expr3, expr4 = expr1, expr2 -.. _summary: +.. _operator-summary: Summary ======= Modified: doctools/trunk/Doc-3k/reference/introduction.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/introduction.rst (original) +++ doctools/trunk/Doc-3k/reference/introduction.rst Thu Aug 2 20:07:46 2007 @@ -29,9 +29,9 @@ you'll find short "implementation notes" sprinkled throughout the text. Every Python implementation comes with a number of built-in and standard -modules. These are not documented here, but in the separate Python Library -Reference (XXX reference: ../lib/lib.html) document. A few built-in modules are -mentioned when they interact in a significant way with the language definition. +modules. These are documented in :ref:`library-index`. A few built-in modules +are mentioned when they interact in a significant way with the language +definition. .. _implementations: Modified: doctools/trunk/Doc-3k/reference/lexical_analysis.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/lexical_analysis.rst (original) +++ doctools/trunk/Doc-3k/reference/lexical_analysis.rst Thu Aug 2 20:07:46 2007 @@ -389,9 +389,9 @@ .. note:: - The name ``_`` is often used in conjunction with internationalization; refer to - the documentation for the :mod:`gettext` module (XXX reference: ../lib/module- - gettext.html) for more information on this convention. + The name ``_`` is often used in conjunction with internationalization; + refer to the documentation for the :mod:`gettext` module for more + information on this convention. ``__*__`` System-defined names. These names are defined by the interpreter and its Modified: doctools/trunk/Doc-3k/reference/simple_stmts.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/simple_stmts.rst (original) +++ doctools/trunk/Doc-3k/reference/simple_stmts.rst Thu Aug 2 20:07:46 2007 @@ -697,9 +697,8 @@ .. index:: builtin: __import__ The built-in function :func:`__import__` is provided to support applications -that determine which modules need to be loaded dynamically; refer to Built-in -Functions (XXX reference: ../lib/built-in-funcs.html) in the Python Library -Reference (XXX reference: ../lib/lib.html) for additional information. +that determine which modules need to be loaded dynamically; refer to +:ref:`built-in-funcs` for additional information. .. _future: @@ -769,9 +768,8 @@ and :func:`execfile` that occur in a module :mod:`M` containing a future statement will, by default, use the new syntax or semantics associated with the future statement. This can, starting with Python 2.2 be controlled by optional -arguments to :func:`compile` --- see the documentation of that function in the -Python Library Reference (XXX reference: ../lib/built-in-funcs.html) for -details. +arguments to :func:`compile` --- see the documentation of that function +for details. A future statement typed at an interactive interpreter prompt will take effect for the rest of the interpreter session. If an interpreter is started with the Modified: doctools/trunk/Doc-3k/tutorial/controlflow.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/controlflow.rst (original) +++ doctools/trunk/Doc-3k/tutorial/controlflow.rst Thu Aug 2 20:07:46 2007 @@ -405,12 +405,12 @@ TypeError: function() got multiple values for keyword argument 'a' When a final formal parameter of the form ``**name`` is present, it receives a -dictionary (XXX reference: ../lib/typesmapping.html) containing all keyword -arguments except for those corresponding to a formal parameter. This may be -combined with a formal parameter of the form ``*name`` (described in the next -subsection) which receives a tuple containing the positional arguments beyond -the formal parameter list. (``*name`` must occur before ``**name``.) For -example, if we define a function like this:: +dictionary (see :ref:`typesmapping`) containing all keyword arguments except for +those corresponding to a formal parameter. This may be combined with a formal +parameter of the form ``*name`` (described in the next subsection) which +receives a tuple containing the positional arguments beyond the formal parameter +list. (``*name`` must occur before ``**name``.) For example, if we define a +function like this:: def cheeseshop(kind, *arguments, **keywords): print "-- Do you have any", kind, '?' Modified: doctools/trunk/Doc-3k/tutorial/datastructures.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/datastructures.rst (original) +++ doctools/trunk/Doc-3k/tutorial/datastructures.rst Thu Aug 2 20:07:46 2007 @@ -47,8 +47,7 @@ is specified, ``a.pop()`` removes and returns the last item in the list. (The square brackets around the *i* in the method signature denote that the parameter is optional, not that you should type square brackets at that position. You - will see this notation frequently in the Python Library Reference (XXX - reference: ../lib/lib.html).) + will see this notation frequently in the Python Library Reference.) .. method:: list.index(x) @@ -271,10 +270,10 @@ ==================== We saw that lists and strings have many common properties, such as indexing and -slicing operations. They are two examples of *sequence* data types (XXX -reference: ../lib/typesseq.html). Since Python is an evolving language, other -sequence data types may be added. There is also another standard sequence data -type: the *tuple*. +slicing operations. They are two examples of *sequence* data types (see +:ref:`typesseq`). Since Python is an evolving language, other sequence data +types may be added. There is also another standard sequence data type: the +*tuple*. A tuple consists of a number of values separated by commas, for instance:: @@ -373,9 +372,9 @@ Dictionaries ============ -Another useful data type built into Python is the *dictionary* (XXX reference: -../lib/typesmapping.html). Dictionaries are sometimes found in other languages -as "associative memories" or "associative arrays". Unlike sequences, which are +Another useful data type built into Python is the *dictionary* (see +:ref:`typesmapping`). Dictionaries are sometimes found in other languages as +"associative memories" or "associative arrays". Unlike sequences, which are indexed by a range of numbers, dictionaries are indexed by *keys*, which can be any immutable type; strings and numbers can always be keys. Tuples can be used as keys if they contain only strings, numbers, or tuples; if a tuple contains Modified: doctools/trunk/Doc-3k/tutorial/errors.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/errors.rst (original) +++ doctools/trunk/Doc-3k/tutorial/errors.rst Thu Aug 2 20:07:46 2007 @@ -71,8 +71,7 @@ traceback listing source lines; however, it will not display lines read from standard input. -The Python Library Reference (XXX reference: ../lib/module-exceptions.html) -lists the built-in exceptions and their meanings. +:ref:`bltin-exceptions` lists the built-in exceptions and their meanings. .. _tut-handling: Modified: doctools/trunk/Doc-3k/tutorial/glossary.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/glossary.rst (original) +++ doctools/trunk/Doc-3k/tutorial/glossary.rst Thu Aug 2 20:07:46 2007 @@ -100,9 +100,9 @@ from __future__ import new_feature - By importing the :mod:`__future__` (XXX reference: ../lib/module-future.html) - module and evaluating its variables, you can see when a new feature was first - added to the language and when it will become the default:: + By importing the :mod:`__future__` module and evaluating its variables, you + can see when a new feature was first added to the language and when it will + become the default:: >>> import __future__ >>> __future__.division @@ -273,9 +273,8 @@ namespaces. Namespaces also aid readability and maintainability by making it clear which module implements a function. For instance, writing :func:`random.seed` or :func:`itertools.izip` makes it clear that those - functions are implemented by the :mod:`random` (XXX reference: ../lib/module- - random.html) and :mod:`itertools` (XXX reference: ../lib/module-itertools.html) - modules respectively. + functions are implemented by the :mod:`random` and :mod:`itertools` modules + respectively. .. index:: single: nested scope Modified: doctools/trunk/Doc-3k/tutorial/inputoutput.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/inputoutput.rst (original) +++ doctools/trunk/Doc-3k/tutorial/inputoutput.rst Thu Aug 2 20:07:46 2007 @@ -323,14 +323,13 @@ complicated. Rather than have users be constantly writing and debugging code to save -complicated data types, Python provides a standard module called :mod:`pickle` -(XXX reference: ../lib/module-pickle.html). This is an amazing module that can -take almost any Python object (even some forms of Python code!), and convert it -to a string representation; this process is called :dfn:`pickling`. -Reconstructing the object from the string representation is called -:dfn:`unpickling`. Between pickling and unpickling, the string representing the -object may have been stored in a file or data, or sent over a network connection -to some distant machine. +complicated data types, Python provides a standard module called :mod:`pickle`. +This is an amazing module that can take almost any Python object (even some +forms of Python code!), and convert it to a string representation; this process +is called :dfn:`pickling`. Reconstructing the object from the string +representation is called :dfn:`unpickling`. Between pickling and unpickling, +the string representing the object may have been stored in a file or data, or +sent over a network connection to some distant machine. If you have an object ``x``, and a file object ``f`` that's been opened for writing, the simplest way to pickle the object takes only one line of code:: @@ -344,15 +343,12 @@ (There are other variants of this, used when pickling many objects or when you don't want to write the pickled data to a file; consult the complete -documentation for :mod:`pickle` (XXX reference: ../lib/module-pickle.html) in -the Python Library Reference (XXX reference: ../lib/).) +documentation for :mod:`pickle` in the Python Library Reference.) -:mod:`pickle` (XXX reference: ../lib/module-pickle.html) is the standard way to -make Python objects which can be stored and reused by other programs or by a -future invocation of the same program; the technical term for this is a -:dfn:`persistent` object. Because :mod:`pickle` (XXX reference: ../lib/module- -pickle.html) is so widely used, many authors who write Python extensions take -care to ensure that new data types such as matrices can be properly pickled and -unpickled. +:mod:`pickle` is the standard way to make Python objects which can be stored and +reused by other programs or by a future invocation of the same program; the +technical term for this is a :dfn:`persistent` object. Because :mod:`pickle` is +so widely used, many authors who write Python extensions take care to ensure +that new data types such as matrices can be properly pickled and unpickled. Modified: doctools/trunk/Doc-3k/tutorial/interactive.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/interactive.rst (original) +++ doctools/trunk/Doc-3k/tutorial/interactive.rst Thu Aug 2 20:07:46 2007 @@ -115,8 +115,8 @@ the startup file is executed in the same namespace as the interactive commands, and removing the names avoids creating side effects in the interactive environment. You may find it convenient to keep some of the imported modules, -such as :mod:`os` (XXX reference: ../lib/module-os.html), which turn out to be -needed in most sessions with the interpreter. :: +such as :mod:`os`, which turn out to be needed in most sessions with the +interpreter. :: # Add auto-completion and a stored history file of commands to your Python # interactive interpreter. Requires Python 2.0+, readline. Autocomplete is Modified: doctools/trunk/Doc-3k/tutorial/interpreter.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/interpreter.rst (original) +++ doctools/trunk/Doc-3k/tutorial/interpreter.rst Thu Aug 2 20:07:46 2007 @@ -182,9 +182,8 @@ With that declaration, all characters in the source file will be treated as having the encoding *encoding*, and it will be possible to directly write Unicode string literals in the selected encoding. The list of possible -encodings can be found in the Python Library Reference (XXX reference: -../lib/lib.html), in the section on :mod:`codecs` (XXX reference: ../lib/module- -codecs.html). +encodings can be found in the Python Library Reference, in the section on +:mod:`codecs`. For example, to write Unicode literals including the Euro currency symbol, the ISO-8859-15 encoding can be used, with the Euro symbol having the ordinal value Modified: doctools/trunk/Doc-3k/tutorial/modules.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/modules.rst (original) +++ doctools/trunk/Doc-3k/tutorial/modules.rst Thu Aug 2 20:07:46 2007 @@ -215,9 +215,8 @@ .. index:: module: compileall -* The module :mod:`compileall` (XXX reference: ../lib/module-compileall.html) - can create :file:`.pyc` files (or :file:`.pyo` files when :option:`-O` is used) - for all modules in a directory. +* The module :mod:`compileall` can create :file:`.pyc` files (or :file:`.pyo` + files when :option:`-O` is used) for all modules in a directory. .. % @@ -230,15 +229,14 @@ .. index:: module: sys Python comes with a library of standard modules, described in a separate -document, the Python Library Reference (XXX reference: ../lib/lib.html) -("Library Reference" hereafter). Some modules are built into the interpreter; -these provide access to operations that are not part of the core of the language -but are nevertheless built in, either for efficiency or to provide access to -operating system primitives such as system calls. The set of such modules is a -configuration option which also depends on the underlying platform For example, -the :mod:`winreg` module is only provided on Windows systems. One particular -module deserves some attention: :mod:`sys` (XXX reference: ../lib/module- -sys.html), which is built into every Python interpreter. The variables +document, the Python Library Reference ("Library Reference" hereafter). Some +modules are built into the interpreter; these provide access to operations that +are not part of the core of the language but are nevertheless built in, either +for efficiency or to provide access to operating system primitives such as +system calls. The set of such modules is a configuration option which also +depends on the underlying platform For example, the :mod:`winreg` module is only +provided on Windows systems. One particular module deserves some attention: +:mod:`sys`, which is built into every Python interpreter. The variables ``sys.ps1`` and ``sys.ps2`` define the strings used as primary and secondary prompts: Modified: doctools/trunk/Doc-3k/tutorial/stdlib.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/stdlib.rst (original) +++ doctools/trunk/Doc-3k/tutorial/stdlib.rst Thu Aug 2 20:07:46 2007 @@ -10,8 +10,8 @@ Operating System Interface ========================== -The :mod:`os` (XXX reference: ../lib/module-os.html) module provides dozens of -functions for interacting with the operating system:: +The :mod:`os` module provides dozens of functions for interacting with the +operating system:: >>> import os >>> os.system('time 0:02') @@ -35,9 +35,8 @@ >>> help(os) <returns an extensive manual page created from the module's docstrings> -For daily file and directory management tasks, the :mod:`shutil` (XXX -reference: ../lib/module-shutil.html) module provides a higher level interface -that is easier to use:: +For daily file and directory management tasks, the :mod:`shutil` module provides +a higher level interface that is easier to use:: >>> import shutil >>> shutil.copyfile('data.db', 'archive.db') @@ -49,8 +48,8 @@ File Wildcards ============== -The :mod:`glob` (XXX reference: ../lib/module-glob.html) module provides a -function for making file lists from directory wildcard searches:: +The :mod:`glob` module provides a function for making file lists from directory +wildcard searches:: >>> import glob >>> glob.glob('*.py') @@ -63,18 +62,17 @@ ====================== Common utility scripts often need to process command line arguments. These -arguments are stored in the :mod:`sys` (XXX reference: ../lib/module-sys.html) -module's *argv* attribute as a list. For instance the following output results -from running ``python demo.py one two three`` at the command line:: +arguments are stored in the :mod:`sys` module's *argv* attribute as a list. For +instance the following output results from running ``python demo.py one two +three`` at the command line:: >>> import sys >>> print sys.argv ['demo.py', 'one', 'two', 'three'] -The :mod:`getopt` (XXX reference: ../lib/module-getopt.html) module processes -*sys.argv* using the conventions of the Unix :func:`getopt` function. More -powerful and flexible command line processing is provided by the :mod:`optparse` -(XXX reference: ../lib/module-optparse.html) module. +The :mod:`getopt` module processes *sys.argv* using the conventions of the Unix +:func:`getopt` function. More powerful and flexible command line processing is +provided by the :mod:`optparse` module. .. _tut-stderr: @@ -82,10 +80,9 @@ Error Output Redirection and Program Termination ================================================ -The :mod:`sys` (XXX reference: ../lib/module-sys.html) module also has -attributes for *stdin*, *stdout*, and *stderr*. The latter is useful for -emitting warnings and error messages to make them visible even when *stdout* has -been redirected:: +The :mod:`sys` module also has attributes for *stdin*, *stdout*, and *stderr*. +The latter is useful for emitting warnings and error messages to make them +visible even when *stdout* has been redirected:: >>> sys.stderr.write('Warning, log file not found starting a new one\n') Warning, log file not found starting a new one @@ -98,9 +95,9 @@ String Pattern Matching ======================= -The :mod:`re` (XXX reference: ../lib/module-re.html) module provides regular -expression tools for advanced string processing. For complex matching and -manipulation, regular expressions offer succinct, optimized solutions:: +The :mod:`re` module provides regular expression tools for advanced string +processing. For complex matching and manipulation, regular expressions offer +succinct, optimized solutions:: >>> import re >>> re.findall(r'\bf[a-z]*', 'which foot or hand fell fastest') @@ -120,8 +117,8 @@ Mathematics =========== -The :mod:`math` (XXX reference: ../lib/module-math.html) module gives access to -the underlying C library functions for floating point math:: +The :mod:`math` module gives access to the underlying C library functions for +floating point math:: >>> import math >>> math.cos(math.pi / 4.0) @@ -129,8 +126,7 @@ >>> math.log(1024, 2) 10.0 -The :mod:`random` (XXX reference: ../lib/module-random.html) module provides -tools for making random selections:: +The :mod:`random` module provides tools for making random selections:: >>> import random >>> random.choice(['apple', 'pear', 'banana']) @@ -149,9 +145,8 @@ =============== There are a number of modules for accessing the internet and processing internet -protocols. Two of the simplest are :mod:`urllib2` (XXX reference: ../lib/module- -urllib2.html) for retrieving data from urls and :mod:`smtplib` (XXX reference: -../lib/module-smtplib.html) for sending mail:: +protocols. Two of the simplest are :mod:`urllib2` for retrieving data from urls +and :mod:`smtplib` for sending mail:: >>> import urllib2 >>> for line in urllib2.urlopen('http://tycho.usno.navy.mil/cgi-bin/timer.pl'): @@ -176,11 +171,11 @@ Dates and Times =============== -The :mod:`datetime` (XXX reference: ../lib/module-datetime.html) module supplies -classes for manipulating dates and times in both simple and complex ways. While -date and time arithmetic is supported, the focus of the implementation is on -efficient member extraction for output formatting and manipulation. The module -also supports objects that are timezone aware. :: +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 +focus of the implementation is on efficient member extraction for output +formatting and manipulation. The module also supports objects that are timezone +aware. :: # dates are easily constructed and formatted >>> from datetime import date @@ -203,10 +198,8 @@ ================ Common data archiving and compression formats are directly supported by modules -including: :mod:`zlib` (XXX reference: ../lib/module-zlib.html), :mod:`gzip` -(XXX reference: ../lib/module-gzip.html), :mod:`bz2` (XXX reference: ../lib -/module-bz2.html), :mod:`zipfile` (XXX reference: ../lib/module-zipfile.html), -and :mod:`tarfile` (XXX reference: ../lib/module-tarfile.html). :: +including: :mod:`zlib`, :mod:`gzip`, :mod:`bz2`, :mod:`zipfile` and +:mod:`tarfile`. :: >>> import zlib >>> s = 'witch which has which witches wrist watch' @@ -232,8 +225,7 @@ For example, it may be tempting to use the tuple packing and unpacking feature instead of the traditional approach to swapping arguments. The :mod:`timeit` -(XXX reference: ../lib/module-timeit.html) module quickly demonstrates a modest -performance advantage:: +module quickly demonstrates a modest performance advantage:: >>> from timeit import Timer >>> Timer('t=a; a=b; b=t', 'a=1; b=2').timeit() @@ -241,9 +233,9 @@ >>> Timer('a,b = b,a', 'a=1; b=2').timeit() 0.54962537085770791 -In contrast to :mod:`timeit`'s fine level of granularity, the :mod:`profile` -(XXX reference: ../lib/module-profile.html) and :mod:`pstats` modules provide -tools for identifying time critical sections in larger blocks of code. +In contrast to :mod:`timeit`'s fine level of granularity, the :mod:`profile` and +:mod:`pstats` modules provide tools for identifying time critical sections in +larger blocks of code. .. _tut-quality-control: @@ -255,12 +247,12 @@ function as it is developed and to run those tests frequently during the development process. -The :mod:`doctest` (XXX reference: ../lib/module-doctest.html) module provides a -tool for scanning a module and validating tests embedded in a program's -docstrings. Test construction is as simple as cutting-and-pasting a typical -call along with its results into the docstring. This improves the documentation -by providing the user with an example and it allows the doctest module to make -sure the code remains true to the documentation:: +The :mod:`doctest` module provides a tool for scanning a module and validating +tests embedded in a program's docstrings. Test construction is as simple as +cutting-and-pasting a typical call along with its results into the docstring. +This improves the documentation by providing the user with an example and it +allows the doctest module to make sure the code remains true to the +documentation:: def average(values): """Computes the arithmetic mean of a list of numbers. @@ -273,9 +265,9 @@ import doctest doctest.testmod() # automatically validate the embedded tests -The :mod:`unittest` (XXX reference: ../lib/module-unittest.html) module is not -as effortless as the :mod:`doctest` module, but it allows a more comprehensive -set of tests to be maintained in a separate file:: +The :mod:`unittest` module is not as effortless as the :mod:`doctest` module, +but it allows a more comprehensive set of tests to be maintained in a separate +file:: import unittest @@ -298,28 +290,24 @@ Python has a "batteries included" philosophy. This is best seen through the sophisticated and robust capabilities of its larger packages. For example: -* The :mod:`xmlrpclib` (XXX reference: ../lib/module-xmlrpclib.html) and - :mod:`SimpleXMLRPCServer` (XXX reference: ../lib/module-SimpleXMLRPCServer.html) - modules make implementing remote procedure calls into an almost trivial task. - Despite the modules names, no direct knowledge or handling of XML is needed. - -* The :mod:`email` (XXX reference: ../lib/module-email.html) package is a - library for managing email messages, including MIME and other RFC 2822-based - message documents. Unlike :mod:`smtplib` and :mod:`poplib` which actually send - and receive messages, the email package has a complete toolset for building or - decoding complex message structures (including attachments) and for implementing - internet encoding and header protocols. - -* The :mod:`xml.dom` (XXX reference: ../lib/module-xml.dom.html) and - :mod:`xml.sax` (XXX reference: ../lib/module-xml.sax.html) packages provide - robust support for parsing this popular data interchange format. Likewise, the - :mod:`csv` (XXX reference: ../lib/module-csv.html) module supports direct reads - and writes in a common database format. Together, these modules and packages - greatly simplify data interchange between python applications and other tools. +* The :mod:`xmlrpclib` and :mod:`SimpleXMLRPCServer` modules make implementing + remote procedure calls into an almost trivial task. Despite the modules + names, no direct knowledge or handling of XML is needed. + +* The :mod:`email` package is a library for managing email messages, including + MIME and other RFC 2822-based message documents. Unlike :mod:`smtplib` and + :mod:`poplib` which actually send and receive messages, the email package has + a complete toolset for building or decoding complex message structures + (including attachments) and for implementing internet encoding and header + protocols. + +* The :mod:`xml.dom` and :mod:`xml.sax` packages provide robust support for + parsing this popular data interchange format. Likewise, the :mod:`csv` module + supports direct reads and writes in a common database format. Together, these + modules and packages greatly simplify data interchange between python + applications and other tools. * Internationalization is supported by a number of modules including - :mod:`gettext` (XXX reference: ../lib/module-gettext.html), :mod:`locale` (XXX - reference: ../lib/module-locale.html), and the :mod:`codecs` (XXX reference: - ../lib/module-codecs.html) package. + :mod:`gettext`, :mod:`locale`, and the :mod:`codecs` package. Modified: doctools/trunk/Doc-3k/tutorial/stdlib2.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/stdlib2.rst (original) +++ doctools/trunk/Doc-3k/tutorial/stdlib2.rst Thu Aug 2 20:07:46 2007 @@ -13,19 +13,17 @@ Output Formatting ================= -The :mod:`repr` (XXX reference: ../lib/module-repr.html) module provides a -version of :func:`repr` customized for abbreviated displays of large or deeply -nested containers:: +The :mod:`repr` module provides a version of :func:`repr` customized for +abbreviated displays of large or deeply nested containers:: >>> import repr >>> repr.repr(set('supercalifragilisticexpialidocious')) "set(['a', 'c', 'd', 'e', 'f', 'g', ...])" -The :mod:`pprint` (XXX reference: ../lib/module-pprint.html) module offers more -sophisticated control over printing both built-in and user defined objects in a -way that is readable by the interpreter. When the result is longer than one -line, the "pretty printer" adds line breaks and indentation to more clearly -reveal data structure:: +The :mod:`pprint` module offers more sophisticated control over printing both +built-in and user defined objects in a way that is readable by the interpreter. +When the result is longer than one line, the "pretty printer" adds line breaks +and indentation to more clearly reveal data structure:: >>> import pprint >>> t = [[[['black', 'cyan'], 'white', ['green', 'red']], [['magenta', @@ -38,8 +36,8 @@ [['magenta', 'yellow'], 'blue']]] -The :mod:`textwrap` (XXX reference: ../lib/module-textwrap.html) module formats -paragraphs of text to fit a given screen width:: +The :mod:`textwrap` module formats paragraphs of text to fit a given screen +width:: >>> import textwrap >>> doc = """The wrap() method is just like fill() except that it returns @@ -52,10 +50,9 @@ instead of one big string with newlines to separate the wrapped lines. -The :mod:`locale` (XXX reference: ../lib/module-locale.html) module accesses a -database of culture specific data formats. The grouping attribute of locale's -format function provides a direct way of formatting numbers with group -separators:: +The :mod:`locale` module accesses a database of culture specific data formats. +The grouping attribute of locale's format function provides a direct way of +formatting numbers with group separators:: >>> import locale >>> locale.setlocale(locale.LC_ALL, 'English_United States.1252') @@ -74,10 +71,9 @@ Templating ========== -The :mod:`string` (XXX reference: ../lib/module-string.html) module includes a -versatile :class:`Template` class with a simplified syntax suitable for editing -by end-users. This allows users to customize their applications without having -to alter the application. +The :mod:`string` module includes a versatile :class:`Template` class with a +simplified syntax suitable for editing by end-users. This allows users to +customize their applications without having to alter the application. The format uses placeholder names formed by ``$`` with valid Python identifiers (alphanumeric characters and underscores). Surrounding the placeholder with @@ -141,11 +137,10 @@ Working with Binary Data Record Layouts ======================================= -The :mod:`struct` (XXX reference: ../lib/module-struct.html) module provides -:func:`pack` and :func:`unpack` functions for working with variable length -binary record formats. The following example shows how to loop through header -information in a ZIP file (with pack codes ``"H"`` and ``"L"`` representing two -and four byte unsigned numbers respectively):: +The :mod:`struct` module provides :func:`pack` and :func:`unpack` functions for +working with variable length binary record formats. The following example shows +how to loop through header information in a ZIP file (with pack codes ``"H"`` +and ``"L"`` representing two and four byte unsigned numbers respectively):: import struct @@ -175,9 +170,8 @@ that accept user input while other tasks run in the background. A related use case is running I/O in parallel with computations in another thread. -The following code shows how the high level :mod:`threading` (XXX reference: -../lib/module-threading.html) module can run tasks in background while the main -program continues to run:: +The following code shows how the high level :mod:`threading` module can run +tasks in background while the main program continues to run:: import threading, zipfile @@ -207,10 +201,9 @@ While those tools are powerful, minor design errors can result in problems that are difficult to reproduce. So, the preferred approach to task coordination is to concentrate all access to a resource in a single thread and then use the -:mod:`Queue` (XXX reference: ../lib/module-Queue.html) module to feed that -thread with requests from other threads. Applications using :class:`Queue` -objects for inter-thread communication and coordination are easier to design, -more readable, and more reliable. +:mod:`Queue` module to feed that thread with requests from other threads. +Applications using :class:`Queue` objects for inter-thread communication and +coordination are easier to design, more readable, and more reliable. .. _tut-logging: @@ -218,9 +211,8 @@ Logging ======= -The :mod:`logging` (XXX reference: ../lib/module-logging.html) module offers a -full featured and flexible logging system. At its simplest, log messages are -sent to a file or to ``sys.stderr``:: +The :mod:`logging` module offers a full featured and flexible logging system. +At its simplest, log messages are sent to a file or to ``sys.stderr``:: import logging logging.debug('Debugging information') @@ -258,11 +250,10 @@ This approach works fine for most applications but occasionally there is a need to track objects only as long as they are being used by something else. Unfortunately, just tracking them creates a reference that makes them permanent. -The :mod:`weakref` (XXX reference: ../lib/module-weakref.html) module provides -tools for tracking objects without creating a reference. When the object is no -longer needed, it is automatically removed from a weakref table and a callback -is triggered for weakref objects. Typical applications include caching objects -that are expensive to create:: +The :mod:`weakref` module provides tools for tracking objects without creating a +reference. When the object is no longer needed, it is automatically removed +from a weakref table and a callback is triggered for weakref objects. Typical +applications include caching objects that are expensive to create:: >>> import weakref, gc >>> class A: @@ -297,11 +288,11 @@ sometimes there is a need for alternative implementations with different performance trade-offs. -The :mod:`array` (XXX reference: ../lib/module-array.html) module provides an -:class:`array()` object that is like a list that stores only homogenous data and -stores it more compactly. The following example shows an array of numbers -stored as two byte unsigned binary numbers (typecode ``"H"``) rather than the -usual 16 bytes per entry for regular lists of python int objects:: +The :mod:`array` module provides an :class:`array()` object that is like a list +that stores only homogenous data and stores it more compactly. The following +example shows an array of numbers stored as two byte unsigned binary numbers +(typecode ``"H"``) rather than the usual 16 bytes per entry for regular lists of +python int objects:: >>> from array import array >>> a = array('H', [4000, 10, 700, 22222]) @@ -310,10 +301,10 @@ >>> a[1:3] array('H', [10, 700]) -The :mod:`collections` (XXX reference: ../lib/module-collections.html) module -provides a :class:`deque()` object that is like a list with faster appends and -pops from the left side but slower lookups in the middle. These objects are well -suited for implementing queues and breadth first tree searches:: +The :mod:`collections` module provides a :class:`deque()` object that is like a +list with faster appends and pops from the left side but slower lookups in the +middle. These objects are well suited for implementing queues and breadth first +tree searches:: >>> from collections import deque >>> d = deque(["task1", "task2", "task3"]) @@ -330,8 +321,8 @@ unsearched.append(m) In addition to alternative list implementations, the library also offers other -tools such as the :mod:`bisect` (XXX reference: ../lib/module-bisect.html) -module with functions for manipulating sorted lists:: +tools such as the :mod:`bisect` module with functions for manipulating sorted +lists:: >>> import bisect >>> scores = [(100, 'perl'), (200, 'tcl'), (400, 'lua'), (500, 'python')] @@ -339,10 +330,10 @@ >>> scores [(100, 'perl'), (200, 'tcl'), (300, 'ruby'), (400, 'lua'), (500, 'python')] -The :mod:`heapq` (XXX reference: ../lib/module-heapq.html) module provides -functions for implementing heaps based on regular lists. The lowest valued -entry is always kept at position zero. This is useful for applications which -repeatedly access the smallest element but do not want to run a full list sort:: +The :mod:`heapq` module provides functions for implementing heaps based on +regular lists. The lowest valued entry is always kept at position zero. This +is useful for applications which repeatedly access the smallest element but do +not want to run a full list sort:: >>> from heapq import heapify, heappop, heappush >>> data = [1, 3, 5, 7, 9, 2, 4, 6, 8, 0] @@ -357,14 +348,14 @@ Decimal Floating Point Arithmetic ================================= -The :mod:`decimal` (XXX reference: ../lib/module-decimal.html) module offers a -:class:`Decimal` datatype for decimal floating point arithmetic. Compared to -the built-in :class:`float` implementation of binary floating point, the new -class is especially helpful for financial applications and other uses which -require exact decimal representation, control over precision, control over -rounding to meet legal or regulatory requirements, tracking of significant -decimal places, or for applications where the user expects the results to match -calculations done by hand. +The :mod:`decimal` module offers a :class:`Decimal` datatype for decimal +floating point arithmetic. Compared to the built-in :class:`float` +implementation of binary floating point, the new class is especially helpful for +financial applications and other uses which require exact decimal +representation, control over precision, control over rounding to meet legal or +regulatory requirements, tracking of significant decimal places, or for +applications where the user expects the results to match calculations done by +hand. For example, calculating a 5% tax on a 70 cent phone charge gives different results in decimal floating point and binary floating point. The difference Modified: doctools/trunk/Doc-3k/tutorial/whatnow.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/whatnow.rst (original) +++ doctools/trunk/Doc-3k/tutorial/whatnow.rst Thu Aug 2 20:07:46 2007 @@ -11,7 +11,7 @@ This tutorial is part of Python's documentation set. Some other documents in the set are: -* Python Library Reference (XXX reference: ../lib/lib.html): +* :ref:`library-index`: You should browse through this manual, which gives complete (though terse) reference material about types, functions, and the modules in the standard @@ -21,12 +21,12 @@ and many other tasks. Skimming through the Library Reference will give you an idea of what's available. -* Installing Python Modules (XXX reference: ../inst/inst.html) explains how to - install external modules written by other Python users. +* :ref:`install-index` explains how to install external modules written by other + Python users. -* Language Reference (XXX reference: ../ref/ref.html): A detailed explanation - of Python's syntax and semantics. It's heavy reading, but is useful as a - complete guide to the language itself. +* :ref:`reference-index`: A detailed explanation of Python's syntax and + semantics. It's heavy reading, but is useful as a complete guide to the + language itself. More Python resources: Modified: doctools/trunk/Doc-3k/whatsnew/2.3.rst ============================================================================== --- doctools/trunk/Doc-3k/whatsnew/2.3.rst (original) +++ doctools/trunk/Doc-3k/whatsnew/2.3.rst Thu Aug 2 20:07:46 2007 @@ -30,10 +30,9 @@ This article doesn't attempt to provide a complete specification of the new features, but instead provides a convenient overview. For full details, you should refer to the documentation for Python 2.3, such as the Python Library -Reference (XXX reference: ../lib/lib.html) and the Python Reference Manual (XXX -reference: ../ref/ref.html). If you want to understand the complete -implementation and design rationale, refer to the PEP for a particular new -feature. +Reference and the Python Reference Manual. If you want to understand the +complete implementation and design rationale, refer to the PEP for a particular +new feature. .. % ====================================================================== @@ -1345,7 +1344,7 @@ elements in the iterator for which the function :func:`predicate` returns :const:`True`, and ``itertools.repeat(obj, N)`` returns ``obj`` *N* times. There are a number of other functions in the module; see the package's reference - documentation (XXX reference: ../lib/module-itertools.html) for details. + documentation for details. (Contributed by Raymond Hettinger.) * Two new functions in the :mod:`math` module, :func:`degrees(rads)` and @@ -1506,8 +1505,7 @@ the text wrapping strategy. Both the :class:`TextWrapper` class and the :func:`wrap` and :func:`fill` functions support a number of additional keyword arguments for fine-tuning the formatting; consult the module's documentation - (XXX reference: ../lib/module-textwrap.html) for details. (Contributed by Greg - Ward.) + for details. (Contributed by Greg Ward.) * The :mod:`thread` and :mod:`threading` modules now have companion modules, :mod:`dummy_thread` and :mod:`dummy_threading`, that provide a do-nothing @@ -1725,8 +1723,8 @@ support for parsing strings and getting back a :class:`date` or :class:`datetime`. -For more information, refer to the module's reference documentation (XXX -reference: ../lib/module-datetime.html). (Contributed by Tim Peters.) +For more information, refer to the module's reference documentation. +(Contributed by Tim Peters.) .. % ====================================================================== @@ -1787,10 +1785,8 @@ set maximum length of output $ -See the module's documentation (XXX reference: ../lib/module-optparse.html) for -more details. +See the module's documentation for more details. -.. % $ prevent Emacs tex-mode from getting confused Optik was written by Greg Ward, with suggestions from the readers of the Getopt SIG. Modified: doctools/trunk/Doc-3k/whatsnew/2.4.rst ============================================================================== --- doctools/trunk/Doc-3k/whatsnew/2.4.rst (original) +++ doctools/trunk/Doc-3k/whatsnew/2.4.rst Thu Aug 2 20:07:46 2007 @@ -25,10 +25,9 @@ This article doesn't attempt to provide a complete specification of every single new feature, but instead provides a brief introduction to each feature. For full details, you should refer to the documentation for Python 2.4, such as the -Python Library Reference (XXX reference: ../lib/lib.html) and the Python -Reference Manual (XXX reference: ../ref/ref.html). Often you will be referred -to the PEP for a particular new feature for explanations of the implementation -and design rationale. +Python Library Reference and the Python Reference Manual. Often you will be +referred to the PEP for a particular new feature for explanations of the +implementation and design rationale. .. % ====================================================================== Modified: doctools/trunk/Doc-3k/whatsnew/2.6.rst ============================================================================== --- doctools/trunk/Doc-3k/whatsnew/2.6.rst (original) +++ doctools/trunk/Doc-3k/whatsnew/2.6.rst Thu Aug 2 20:07:46 2007 @@ -3,8 +3,8 @@ **************************** :Author: A.M. Kuchling - -.. |release| replace:: 0.0 +:Release: |release| +:Date: |today| .. % $Id: whatsnew26.tex 55963 2007-06-13 18:07:49Z guido.van.rossum $ .. % Rules for maintenance:

1 0

r56673 - peps/trunk/pep-3115.txt
by guido.van.rossum Aug. 2, 2007

Aug. 2, 2007

Author: guido.van.rossum Date: Thu Aug 2 18:51:59 2007 New Revision: 56673 Modified: peps/trunk/pep-3115.txt Log: Mention that type.__prepare__() exists for use via super(). Modified: peps/trunk/pep-3115.txt ============================================================================== --- peps/trunk/pep-3115.txt (original) +++ peps/trunk/pep-3115.txt Thu Aug 2 18:51:59 2007 @@ -132,6 +132,10 @@ assignment algorithm. (Note also that 'metaclass' is a keyword- only argument as per PEP 3102 [6].) + Even though __prepare__ is not required, the default metaclass + ('type') implements it, for the convenience of subclasses calling + it via super(). + __prepare__ returns a dictionary-like object which is used to store the class member definitions during evaluation of the class body. In other words, the class body is evaluated as a function block

1 0

r56671 - in doctools/trunk/Doc-3k: library/ast.rst reference/expressions.rst reference/simple_stmts.rst
by georg.brandl Aug. 2, 2007

Aug. 2, 2007

Author: georg.brandl Date: Thu Aug 2 18:13:06 2007 New Revision: 56671 Removed: doctools/trunk/Doc-3k/library/ast.rst Modified: doctools/trunk/Doc-3k/reference/expressions.rst doctools/trunk/Doc-3k/reference/simple_stmts.rst Log: Extra 3k fixes. Deleted: /doctools/trunk/Doc-3k/library/ast.rst ============================================================================== --- /doctools/trunk/Doc-3k/library/ast.rst Thu Aug 2 18:13:06 2007 +++ (empty file) @@ -1,62 +0,0 @@ -.. % XXX Label can't be _ast? -.. % XXX Where should this section/chapter go? - - -.. _ast: - -********************* -Abstract Syntax Trees -********************* - -.. sectionauthor:: Martin v. Löwis <martin(a)v.loewis.de> - - -.. versionadded:: 2.5 - -The ``_ast`` module helps Python applications to process trees of the Python -abstract syntax grammar. The Python compiler currently provides read-only access -to such trees, meaning that applications can only create a tree for a given -piece of Python source code; generating byte code from a (potentially modified) -tree is not supported. The abstract syntax itself might change with each Python -release; this module helps to find out programmatically what the current grammar -looks like. - -An abstract syntax tree can be generated by passing ``_ast.PyCF_ONLY_AST`` as a -flag to the :func:`compile` builtin function. The result will be a tree of -objects whose classes all inherit from ``_ast.AST``. - -The actual classes are derived from the ``Parser/Python.asdl`` file, which is -reproduced below. There is one class defined for each left-hand side symbol in -the abstract grammar (for example, ``_ast.stmt`` or ``_ast.expr``). In addition, -there is one class defined for each constructor on the right-hand side; these -classes inherit from the classes for the left-hand side trees. For example, -``_ast.BinOp`` inherits from ``_ast.expr``. For production rules with -alternatives (aka "sums"), the left-hand side class is abstract: only instances -of specific constructor nodes are ever created. - -Each concrete class has an attribute ``_fields`` which gives the names of all -child nodes. - -Each instance of a concrete class has one attribute for each child node, of the -type as defined in the grammar. For example, ``_ast.BinOp`` instances have an -attribute ``left`` of type ``_ast.expr``. Instances of ``_ast.expr`` and -``_ast.stmt`` subclasses also have lineno and col_offset attributes. The lineno -is the line number of source text (1 indexed so the first line is line 1) and -the col_offset is the utf8 byte offset of the first token that generated the -node. The utf8 offset is recorded because the parser uses utf8 internally. - -If these attributes are marked as optional in the grammar (using a question -mark), the value might be ``None``. If the attributes can have zero-or-more -values (marked with an asterisk), the values are represented as Python lists. - - -Abstract Grammar -================ - -The module defines a string constant ``__version__`` which is the decimal -subversion revision number of the file shown below. - -The abstract grammar is currently defined as follows: - - -.. XXX includefile ../../Parser/Python.asdl Modified: doctools/trunk/Doc-3k/reference/expressions.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/expressions.rst (original) +++ doctools/trunk/Doc-3k/reference/expressions.rst Thu Aug 2 18:13:06 2007 @@ -31,9 +31,11 @@ .. index:: pair: arithmetic; conversion +.. XXX no coercion rules are documented anymore + When a description of an arithmetic operator below uses the phrase "the numeric arguments are converted to a common type," the arguments are coerced using the -coercion rules listed at :ref:`coercion-rules`. If both arguments are standard +coercion rules. If both arguments are standard numeric types, the following coercions are applied: * If either argument is a complex number, the other is converted to complex; Modified: doctools/trunk/Doc-3k/reference/simple_stmts.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/simple_stmts.rst (original) +++ doctools/trunk/Doc-3k/reference/simple_stmts.rst Thu Aug 2 18:13:06 2007 @@ -59,7 +59,7 @@ In interactive mode, if the value is not ``None``, it is converted to a string using the built-in :func:`repr` function and the resulting string is written to -standard output (see section :ref:`print`) on a line by itself. (Expression +standard output (see :func:`print`) on a line by itself. (Expression statements yielding ``None`` are not written, so that procedure calls do not cause any output.)

1 0

r56670 - in doctools/trunk: Doc-26/TODO Doc-26/c-api/concrete.rst Doc-26/c-api/intro.rst Doc-26/conf.py Doc-26/distutils/apiref.rst Doc-26/distutils/introduction.rst Doc-26/distutils/setupscript.rst Doc-26/distutils/sourcedist.rst Doc-26/distutils/sysconfig.rst Doc-26/extending/extending.rst Doc-26/extending/index.rst Doc-26/library/asttable.rst Doc-26/library/compiler.rst Doc-26/library/contextlib.rst Doc-26/library/cookielib.rst Doc-26/library/idle.rst Doc-26/library/index.rst Doc-26/lib
by georg.brandl Aug. 2, 2007

Aug. 2, 2007

Author: georg.brandl Date: Thu Aug 2 17:44:40 2007 New Revision: 56670 Added: doctools/trunk/Doc-26/library/idle.rst doctools/trunk/Doc-26/library/othergui.rst doctools/trunk/Doc-26/library/scrolledtext.rst doctools/trunk/Doc-26/library/tix.rst doctools/trunk/Doc-26/library/tk.rst doctools/trunk/Doc-3k/library/idle.rst doctools/trunk/Doc-3k/library/othergui.rst doctools/trunk/Doc-3k/library/scrolledtext.rst doctools/trunk/Doc-3k/library/tix.rst doctools/trunk/Doc-3k/library/tk.rst Removed: doctools/trunk/Doc-26/distutils/sysconfig.rst doctools/trunk/Doc-26/library/asttable.rst doctools/trunk/Doc-3k/distutils/sysconfig.rst doctools/trunk/Doc-3k/library/asttable.rst Modified: doctools/trunk/Doc-26/TODO doctools/trunk/Doc-26/c-api/concrete.rst doctools/trunk/Doc-26/c-api/intro.rst doctools/trunk/Doc-26/conf.py doctools/trunk/Doc-26/distutils/apiref.rst doctools/trunk/Doc-26/distutils/introduction.rst doctools/trunk/Doc-26/distutils/setupscript.rst doctools/trunk/Doc-26/distutils/sourcedist.rst doctools/trunk/Doc-26/extending/extending.rst doctools/trunk/Doc-26/extending/index.rst doctools/trunk/Doc-26/library/compiler.rst doctools/trunk/Doc-26/library/contextlib.rst doctools/trunk/Doc-26/library/cookielib.rst doctools/trunk/Doc-26/library/index.rst doctools/trunk/Doc-26/library/intro.rst doctools/trunk/Doc-26/library/sqlite3.rst doctools/trunk/Doc-26/library/stdtypes.rst doctools/trunk/Doc-26/library/strings.rst doctools/trunk/Doc-26/library/tarfile.rst doctools/trunk/Doc-26/library/tkinter.rst doctools/trunk/Doc-26/library/xml.dom.minidom.rst doctools/trunk/Doc-26/reference/compound_stmts.rst doctools/trunk/Doc-26/reference/datamodel.rst doctools/trunk/Doc-26/reference/simple_stmts.rst doctools/trunk/Doc-3k/TODO doctools/trunk/Doc-3k/c-api/concrete.rst doctools/trunk/Doc-3k/c-api/intro.rst doctools/trunk/Doc-3k/conf.py doctools/trunk/Doc-3k/distutils/apiref.rst doctools/trunk/Doc-3k/distutils/introduction.rst doctools/trunk/Doc-3k/distutils/setupscript.rst doctools/trunk/Doc-3k/distutils/sourcedist.rst doctools/trunk/Doc-3k/extending/extending.rst doctools/trunk/Doc-3k/extending/index.rst doctools/trunk/Doc-3k/library/contextlib.rst doctools/trunk/Doc-3k/library/cookielib.rst doctools/trunk/Doc-3k/library/index.rst doctools/trunk/Doc-3k/library/intro.rst doctools/trunk/Doc-3k/library/sqlite3.rst doctools/trunk/Doc-3k/library/stdtypes.rst doctools/trunk/Doc-3k/library/strings.rst doctools/trunk/Doc-3k/library/tarfile.rst doctools/trunk/Doc-3k/library/tkinter.rst doctools/trunk/Doc-3k/library/xml.dom.minidom.rst doctools/trunk/Doc-3k/reference/compound_stmts.rst doctools/trunk/Doc-3k/reference/datamodel.rst doctools/trunk/Doc-3k/reference/simple_stmts.rst Log: Vanquish all remaining build warnings. Modified: doctools/trunk/Doc-26/TODO ============================================================================== --- doctools/trunk/Doc-26/TODO (original) +++ doctools/trunk/Doc-26/TODO Thu Aug 2 17:44:40 2007 @@ -2,7 +2,6 @@ ====================== * fix all references and links marked with `XXX` -* fix all duplicate labels and undefined label references * split very large files and add toctrees * integrate standalone HOWTOs * find out which files get "comments disabled" metadata Modified: doctools/trunk/Doc-26/c-api/concrete.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/concrete.rst (original) +++ doctools/trunk/Doc-26/c-api/concrete.rst Thu Aug 2 17:44:40 2007 @@ -2934,7 +2934,7 @@ .. versionadded:: 2.3 -.. _weakref-objects: +.. _weakrefobjects: Weak Reference Objects ---------------------- @@ -3168,7 +3168,7 @@ *NULL*. -.. _datetime-objects: +.. _datetimeobjects: DateTime Objects ---------------- Modified: doctools/trunk/Doc-26/c-api/intro.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/intro.rst (original) +++ doctools/trunk/Doc-26/c-api/intro.rst Thu Aug 2 17:44:40 2007 @@ -1,7 +1,7 @@ .. highlightlang:: c -.. _intro: +.. _api-intro: ************ Introduction @@ -30,7 +30,7 @@ application. -.. _includes: +.. _api-includes: Include Files ============= @@ -80,7 +80,7 @@ is no need to do anything special to use the API from C++. -.. _objects: +.. _api-objects: Objects, Types and Reference Counts =================================== @@ -107,7 +107,7 @@ pointed to by *a* is a Python list. -.. _refcounts: +.. _api-refcounts: Reference Counts ---------------- @@ -170,7 +170,7 @@ they are done with the result; this soon becomes second nature. -.. _refcountdetails: +.. _api-refcountdetails: Reference Count Details ^^^^^^^^^^^^^^^^^^^^^^^ @@ -335,7 +335,7 @@ .. index:: single: sum_sequence() -.. _types: +.. _api-types: Types ----- @@ -349,7 +349,7 @@ use them. -.. _exceptions: +.. _api-exceptions: Exceptions ========== @@ -501,7 +501,7 @@ the final call made is successful. -.. _embedding: +.. _api-embedding: Embedding Python ================ @@ -525,8 +525,6 @@ :mod:`__builtin__`, :mod:`__main__`, :mod:`sys`, and :mod:`exceptions`. It also initializes the module search path (``sys.path``). -.. % - .. index:: single: PySys_SetArgv() :cfunc:`Py_Initialize` does not set the "script argument list" (``sys.argv``). @@ -579,7 +577,7 @@ allocated by extension modules currently cannot be released. -.. _debugging: +.. _api-debugging: Debugging Builds ================ Modified: doctools/trunk/Doc-26/conf.py ============================================================================== --- doctools/trunk/Doc-26/conf.py (original) +++ doctools/trunk/Doc-26/conf.py Thu Aug 2 17:44:40 2007 @@ -33,6 +33,7 @@ 'whatsnew/2.5.rst', 'maclib/scrap.rst', 'library/xmllib.rst', + 'library/xml.etree.rst', ] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, Modified: doctools/trunk/Doc-26/distutils/apiref.rst ============================================================================== --- doctools/trunk/Doc-26/distutils/apiref.rst (original) +++ doctools/trunk/Doc-26/distutils/apiref.rst Thu Aug 2 17:44:40 2007 @@ -1415,7 +1415,118 @@ Also provides :func:`find_executable` to search the path for a given executable name. -XXX: input{sysconfig} :XXX + +:mod:`distutils.sysconfig` --- System configuration information +=============================================================== + +.. module:: distutils.sysconfig + :synopsis: Low-level access to configuration information of the Python interpreter. +.. moduleauthor:: Fred L. Drake, Jr. <fdrake(a)acm.org> +.. moduleauthor:: Greg Ward <gward(a)python.net> +.. sectionauthor:: Fred L. Drake, Jr. <fdrake(a)acm.org> + + +The :mod:`distutils.sysconfig` module provides access to Python's low-level +configuration information. The specific configuration variables available +depend heavily on the platform and configuration. The specific variables depend +on the build process for the specific version of Python being run; the variables +are those found in the :file:`Makefile` and configuration header that are +installed with Python on Unix systems. The configuration header is called +:file:`pyconfig.h` for Python versions starting with 2.2, and :file:`config.h` +for earlier versions of Python. + +Some additional functions are provided which perform some useful manipulations +for other parts of the :mod:`distutils` package. + + +.. data:: PREFIX + + The result of ``os.path.normpath(sys.prefix)``. + + +.. data:: EXEC_PREFIX + + The result of ``os.path.normpath(sys.exec_prefix)``. + + +.. function:: get_config_var(name) + + Return the value of a single variable. This is equivalent to + ``get_config_vars().get(name)``. + + +.. function:: get_config_vars(...) + + Return a set of variable definitions. If there are no arguments, this returns a + dictionary mapping names of configuration variables to values. If arguments are + provided, they should be strings, and the return value will be a sequence giving + the associated values. If a given name does not have a corresponding value, + ``None`` will be included for that variable. + + +.. function:: get_config_h_filename() + + Return the full path name of the configuration header. For Unix, this will be + the header generated by the :program:`configure` script; for other platforms the + header will have been supplied directly by the Python source distribution. The + file is a platform-specific text file. + + +.. function:: get_makefile_filename() + + Return the full path name of the :file:`Makefile` used to build Python. For + Unix, this will be a file generated by the :program:`configure` script; the + meaning for other platforms will vary. The file is a platform-specific text + file, if it exists. This function is only useful on POSIX platforms. + + +.. function:: get_python_inc([plat_specific[, prefix]]) + + Return the directory for either the general or platform-dependent C include + files. If *plat_specific* is true, the platform-dependent include directory is + returned; if false or omitted, the platform-independent directory is returned. + If *prefix* is given, it is used as either the prefix instead of + :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if + *plat_specific* is true. + + +.. function:: get_python_lib([plat_specific[, standard_lib[, prefix]]]) + + Return the directory for either the general or platform-dependent library + installation. If *plat_specific* is true, the platform-dependent include + directory is returned; if false or omitted, the platform-independent directory + is returned. If *prefix* is given, it is used as either the prefix instead of + :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if + *plat_specific* is true. If *standard_lib* is true, the directory for the + standard library is returned rather than the directory for the installation of + third-party extensions. + +The following function is only intended for use within the :mod:`distutils` +package. + + +.. function:: customize_compiler(compiler) + + Do any platform-specific customization of a + :class:`distutils.ccompiler.CCompiler` instance. + + This function is only needed on Unix at this time, but should be called + consistently to support forward-compatibility. It inserts the information that + varies across Unix flavors and is stored in Python's :file:`Makefile`. This + information includes the selected compiler, compiler and linker options, and the + extension used by the linker for shared objects. + +This function is even more special-purpose, and should only be used from +Python's own build procedures. + + +.. function:: set_python_build() + + Inform the :mod:`distutils.sysconfig` module that it is being used as part of + the build process for Python. This changes a lot of relative locations for + files, allowing them to be located in the build area rather than in an installed + Python. + :mod:`distutils.text_file` --- The TextFile class ================================================= @@ -1870,20 +1981,3 @@ *sub_commands* is usually defined at the \*end\* of a class, because predicates can be unbound methods, so they must already have been defined. The canonical example is the :command:`install` command. - -.. % -.. % The ugly "%begin{latexonly}" pseudo-environments are really just to -.. % keep LaTeX2HTML quiet during the \renewcommand{} macros; they're -.. % not really valuable. -.. % -.. % begin{latexonly} -.. % end{latexonly} - -XXX: input{moddist.ind} :XXX -.. % Module Index -.. % begin{latexonly} -.. % end{latexonly} - -XXX: input{dist.ind} :XXX -.. % Index - Modified: doctools/trunk/Doc-26/distutils/introduction.rst ============================================================================== --- doctools/trunk/Doc-26/distutils/introduction.rst (original) +++ doctools/trunk/Doc-26/distutils/introduction.rst Thu Aug 2 17:44:40 2007 @@ -1,4 +1,4 @@ -.. _intro: +.. _distutils-intro: **************************** An Introduction to Distutils @@ -10,7 +10,7 @@ Python Modules (XXX reference: ../inst/inst.html) manual. -.. _concepts: +.. _distutils-concepts: Concepts & Terminology ====================== @@ -41,7 +41,7 @@ code. -.. _simple-example: +.. _distutils-simple-example: A Simple Example ================ Modified: doctools/trunk/Doc-26/distutils/setupscript.rst ============================================================================== --- doctools/trunk/Doc-26/distutils/setupscript.rst (original) +++ doctools/trunk/Doc-26/distutils/setupscript.rst Thu Aug 2 17:44:40 2007 @@ -8,7 +8,7 @@ installing modules using the Distutils. The main purpose of the setup script is to describe your module distribution to the Distutils, so that the various commands that operate on your modules do the right thing. As we saw in section -:ref:`simple-example` above, the setup script consists mainly of a call to +:ref:`distutils-simple-example` above, the setup script consists mainly of a call to :func:`setup`, and most information supplied to the Distutils by the module developer is supplied as keyword arguments to :func:`setup`. @@ -33,7 +33,7 @@ ) There are only two differences between this and the trivial one-file -distribution presented in section :ref:`simple-example`: more metadata, and the +distribution presented in section :ref:`distutils-simple-example`: more metadata, and the specification of pure Python modules by package, rather than by module. This is important since the Distutils consist of a couple of dozen modules split into (so far) two packages; an explicit list of every module would be tedious to @@ -114,7 +114,7 @@ For a small module distribution, you might prefer to list all modules rather than listing packages---especially the case of a single module that goes in the "root package" (i.e., no package at all). This simplest case was shown in -section :ref:`simple-example`; here is a slightly more involved example:: +section :ref:`distutils-simple-example`; here is a slightly more involved example:: py_modules = ['mod1', 'pkg.mod2'] Modified: doctools/trunk/Doc-26/distutils/sourcedist.rst ============================================================================== --- doctools/trunk/Doc-26/distutils/sourcedist.rst (original) +++ doctools/trunk/Doc-26/distutils/sourcedist.rst Thu Aug 2 17:44:40 2007 @@ -4,7 +4,7 @@ Creating a Source Distribution ****************************** -As shown in section :ref:`simple-example`, you use the :command:`sdist` command +As shown in section :ref:`distutils-simple-example`, you use the :command:`sdist` command to create a source distribution. In the simplest case, :: python setup.py sdist Deleted: /doctools/trunk/Doc-26/distutils/sysconfig.rst ============================================================================== --- /doctools/trunk/Doc-26/distutils/sysconfig.rst Thu Aug 2 17:44:40 2007 +++ (empty file) @@ -1,112 +0,0 @@ - -:mod:`distutils.sysconfig` --- System configuration information -=============================================================== - -.. module:: distutils.sysconfig - :synopsis: Low-level access to configuration information of the Python interpreter. -.. moduleauthor:: Fred L. Drake, Jr. <fdrake(a)acm.org> -.. moduleauthor:: Greg Ward <gward(a)python.net> -.. sectionauthor:: Fred L. Drake, Jr. <fdrake(a)acm.org> - - -The :mod:`distutils.sysconfig` module provides access to Python's low-level -configuration information. The specific configuration variables available -depend heavily on the platform and configuration. The specific variables depend -on the build process for the specific version of Python being run; the variables -are those found in the :file:`Makefile` and configuration header that are -installed with Python on Unix systems. The configuration header is called -:file:`pyconfig.h` for Python versions starting with 2.2, and :file:`config.h` -for earlier versions of Python. - -Some additional functions are provided which perform some useful manipulations -for other parts of the :mod:`distutils` package. - - -.. data:: PREFIX - - The result of ``os.path.normpath(sys.prefix)``. - - -.. data:: EXEC_PREFIX - - The result of ``os.path.normpath(sys.exec_prefix)``. - - -.. function:: get_config_var(name) - - Return the value of a single variable. This is equivalent to - ``get_config_vars().get(name)``. - - -.. function:: get_config_vars(...) - - Return a set of variable definitions. If there are no arguments, this returns a - dictionary mapping names of configuration variables to values. If arguments are - provided, they should be strings, and the return value will be a sequence giving - the associated values. If a given name does not have a corresponding value, - ``None`` will be included for that variable. - - -.. function:: get_config_h_filename() - - Return the full path name of the configuration header. For Unix, this will be - the header generated by the :program:`configure` script; for other platforms the - header will have been supplied directly by the Python source distribution. The - file is a platform-specific text file. - - -.. function:: get_makefile_filename() - - Return the full path name of the :file:`Makefile` used to build Python. For - Unix, this will be a file generated by the :program:`configure` script; the - meaning for other platforms will vary. The file is a platform-specific text - file, if it exists. This function is only useful on POSIX platforms. - - -.. function:: get_python_inc([plat_specific[, prefix]]) - - Return the directory for either the general or platform-dependent C include - files. If *plat_specific* is true, the platform-dependent include directory is - returned; if false or omitted, the platform-independent directory is returned. - If *prefix* is given, it is used as either the prefix instead of - :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if - *plat_specific* is true. - - -.. function:: get_python_lib([plat_specific[, standard_lib[, prefix]]]) - - Return the directory for either the general or platform-dependent library - installation. If *plat_specific* is true, the platform-dependent include - directory is returned; if false or omitted, the platform-independent directory - is returned. If *prefix* is given, it is used as either the prefix instead of - :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if - *plat_specific* is true. If *standard_lib* is true, the directory for the - standard library is returned rather than the directory for the installation of - third-party extensions. - -The following function is only intended for use within the :mod:`distutils` -package. - - -.. function:: customize_compiler(compiler) - - Do any platform-specific customization of a - :class:`distutils.ccompiler.CCompiler` instance. - - This function is only needed on Unix at this time, but should be called - consistently to support forward-compatibility. It inserts the information that - varies across Unix flavors and is stored in Python's :file:`Makefile`. This - information includes the selected compiler, compiler and linker options, and the - extension used by the linker for shared objects. - -This function is even more special-purpose, and should only be used from -Python's own build procedures. - - -.. function:: set_python_build() - - Inform the :mod:`distutils.sysconfig` module that it is being used as part of - the build process for Python. This changes a lot of relative locations for - files, allowing them to be located in the build area rather than in an installed - Python. - Modified: doctools/trunk/Doc-26/extending/extending.rst ============================================================================== --- doctools/trunk/Doc-26/extending/extending.rst (original) +++ doctools/trunk/Doc-26/extending/extending.rst Thu Aug 2 17:44:40 2007 @@ -1,7 +1,7 @@ .. highlightlang:: c -.. _intro: +.. _extending-intro: ****************************** Extending Python with C or C++ @@ -21,7 +21,7 @@ your system setup; details are given in later chapters. -.. _simpleexample: +.. _extending-simpleexample: A Simple Example ================ @@ -103,7 +103,7 @@ return *NULL* immediately (as we saw in the example). -.. _errors: +.. _extending-errors: Intermezzo: Errors and Exceptions ================================= @@ -1109,8 +1109,8 @@ this macro before accessing the C API. The exporting module is a modification of the :mod:`spam` module from section -:ref:`simpleexample`. The function :func:`spam.system` does not call the C -library function :cfunc:`system` directly, but a function +:ref:`extending-simpleexample`. The function :func:`spam.system` does not call +the C library function :cfunc:`system` directly, but a function :cfunc:`PySpam_System`, which would of course do something more complicated in reality (such as adding "spam" to every command). This function :cfunc:`PySpam_System` is also exported to other extension modules. Modified: doctools/trunk/Doc-26/extending/index.rst ============================================================================== --- doctools/trunk/Doc-26/extending/index.rst (original) +++ doctools/trunk/Doc-26/extending/index.rst Thu Aug 2 17:44:40 2007 @@ -17,7 +17,7 @@ This document assumes basic knowledge about Python. For an informal introduction to the language, see :ref:`tutorial-index`. :ref:`reference-index` -gives a more formal definition of the language. :ref:`modules-index` documents +gives a more formal definition of the language. :ref:`library-index` documents the existing object types, functions and modules (both built-in and written in Python) that give the language its wide application range. Deleted: /doctools/trunk/Doc-26/library/asttable.rst ============================================================================== --- /doctools/trunk/Doc-26/library/asttable.rst Thu Aug 2 17:44:40 2007 +++ (empty file) @@ -1,290 +0,0 @@ -+-----------------------+--------------------+---------------------------------+ -| Node type | Attribute | Value | -+=======================+====================+=================================+ -| :class:`Add` | :attr:`left` | left operand | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | right operand | -+-----------------------+--------------------+---------------------------------+ -| :class:`And` | :attr:`nodes` | list of operands | -+-----------------------+--------------------+---------------------------------+ -| :class:`AssAttr` | | *attribute as target of | -| | | assignment* | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`expr` | expression on the left-hand | -| | | side of the dot | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`attrname` | the attribute name, a string | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`flags` | XXX | -+-----------------------+--------------------+---------------------------------+ -| :class:`AssList` | :attr:`nodes` | list of list elements being | -| | | assigned to | -+-----------------------+--------------------+---------------------------------+ -| :class:`AssName` | :attr:`name` | name being assigned to | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`flags` | XXX | -+-----------------------+--------------------+---------------------------------+ -| :class:`AssTuple` | :attr:`nodes` | list of tuple elements being | -| | | assigned to | -+-----------------------+--------------------+---------------------------------+ -| :class:`Assert` | :attr:`test` | the expression to be tested | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`fail` | the value of the | -| | | :exc:`AssertionError` | -+-----------------------+--------------------+---------------------------------+ -| :class:`Assign` | :attr:`nodes` | a list of assignment targets, | -| | | one per equal sign | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`expr` | the value being assigned | -+-----------------------+--------------------+---------------------------------+ -| :class:`AugAssign` | :attr:`node` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`op` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Backquote` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Bitand` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Bitor` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Bitxor` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Break` | | | -+-----------------------+--------------------+---------------------------------+ -| :class:`CallFunc` | :attr:`node` | expression for the callee | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`args` | a list of arguments | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`star_args` | the extended \*-arg value | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`dstar_args` | the extended \*\*-arg value | -+-----------------------+--------------------+---------------------------------+ -| :class:`Class` | :attr:`name` | the name of the class, a string | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`bases` | a list of base classes | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`doc` | doc string, a string or | -| | | ``None`` | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`code` | the body of the class statement | -+-----------------------+--------------------+---------------------------------+ -| :class:`Compare` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`ops` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Const` | :attr:`value` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Continue` | | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Decorators` | :attr:`nodes` | List of function decorator | -| | | expressions | -+-----------------------+--------------------+---------------------------------+ -| :class:`Dict` | :attr:`items` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Discard` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Div` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Ellipsis` | | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Expression` | :attr:`node` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Exec` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`locals` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`globals` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`FloorDiv` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`For` | :attr:`assign` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`list` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`body` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`else_` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`From` | :attr:`modname` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`names` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Function` | :attr:`decorators` | :class:`Decorators` or ``None`` | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`name` | name used in def, a string | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`argnames` | list of argument names, as | -| | | strings | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`defaults` | list of default values | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`flags` | xxx | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`doc` | doc string, a string or | -| | | ``None`` | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`code` | the body of the function | -+-----------------------+--------------------+---------------------------------+ -| :class:`GenExpr` | :attr:`code` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`GenExprFor` | :attr:`assign` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`iter` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`ifs` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`GenExprIf` | :attr:`test` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`GenExprInner` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`quals` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Getattr` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`attrname` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Global` | :attr:`names` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`If` | :attr:`tests` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`else_` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Import` | :attr:`names` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Invert` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Keyword` | :attr:`name` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Lambda` | :attr:`argnames` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`defaults` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`flags` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`code` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`LeftShift` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`List` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`ListComp` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`quals` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`ListCompFor` | :attr:`assign` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`list` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`ifs` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`ListCompIf` | :attr:`test` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Mod` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Module` | :attr:`doc` | doc string, a string or | -| | | ``None`` | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`node` | body of the module, a | -| | | :class:`Stmt` | -+-----------------------+--------------------+---------------------------------+ -| :class:`Mul` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Name` | :attr:`name` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Not` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Or` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Pass` | | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Power` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Print` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`dest` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Printnl` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`dest` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Raise` | :attr:`expr1` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`expr2` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`expr3` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Return` | :attr:`value` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`RightShift` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Slice` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`flags` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`lower` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`upper` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Sliceobj` | :attr:`nodes` | list of statements | -+-----------------------+--------------------+---------------------------------+ -| :class:`Stmt` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Sub` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Subscript` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`flags` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`subs` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`TryExcept` | :attr:`body` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`handlers` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`else_` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`TryFinally` | :attr:`body` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`final` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Tuple` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`UnaryAdd` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`UnarySub` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`While` | :attr:`test` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`body` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`else_` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`With` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`vars` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`body` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Yield` | :attr:`value` | | -+-----------------------+--------------------+---------------------------------+ - Modified: doctools/trunk/Doc-26/library/compiler.rst ============================================================================== --- doctools/trunk/Doc-26/library/compiler.rst (original) +++ doctools/trunk/Doc-26/library/compiler.rst Thu Aug 2 17:44:40 2007 @@ -213,7 +213,296 @@ order in which they are returned by :meth:`getChildren` and :meth:`getChildNodes`. -XXX: input{asttable} :XXX ++-----------------------+--------------------+---------------------------------+ +| Node type | Attribute | Value | ++=======================+====================+=================================+ +| :class:`Add` | :attr:`left` | left operand | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`right` | right operand | ++-----------------------+--------------------+---------------------------------+ +| :class:`And` | :attr:`nodes` | list of operands | ++-----------------------+--------------------+---------------------------------+ +| :class:`AssAttr` | | *attribute as target of | +| | | assignment* | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`expr` | expression on the left-hand | +| | | side of the dot | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`attrname` | the attribute name, a string | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`flags` | XXX | ++-----------------------+--------------------+---------------------------------+ +| :class:`AssList` | :attr:`nodes` | list of list elements being | +| | | assigned to | ++-----------------------+--------------------+---------------------------------+ +| :class:`AssName` | :attr:`name` | name being assigned to | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`flags` | XXX | ++-----------------------+--------------------+---------------------------------+ +| :class:`AssTuple` | :attr:`nodes` | list of tuple elements being | +| | | assigned to | ++-----------------------+--------------------+---------------------------------+ +| :class:`Assert` | :attr:`test` | the expression to be tested | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`fail` | the value of the | +| | | :exc:`AssertionError` | ++-----------------------+--------------------+---------------------------------+ +| :class:`Assign` | :attr:`nodes` | a list of assignment targets, | +| | | one per equal sign | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`expr` | the value being assigned | ++-----------------------+--------------------+---------------------------------+ +| :class:`AugAssign` | :attr:`node` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`op` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Backquote` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Bitand` | :attr:`nodes` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Bitor` | :attr:`nodes` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Bitxor` | :attr:`nodes` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Break` | | | ++-----------------------+--------------------+---------------------------------+ +| :class:`CallFunc` | :attr:`node` | expression for the callee | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`args` | a list of arguments | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`star_args` | the extended \*-arg value | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`dstar_args` | the extended \*\*-arg value | ++-----------------------+--------------------+---------------------------------+ +| :class:`Class` | :attr:`name` | the name of the class, a string | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`bases` | a list of base classes | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`doc` | doc string, a string or | +| | | ``None`` | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`code` | the body of the class statement | ++-----------------------+--------------------+---------------------------------+ +| :class:`Compare` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`ops` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Const` | :attr:`value` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Continue` | | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Decorators` | :attr:`nodes` | List of function decorator | +| | | expressions | ++-----------------------+--------------------+---------------------------------+ +| :class:`Dict` | :attr:`items` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Discard` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Div` | :attr:`left` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`right` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Ellipsis` | | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Expression` | :attr:`node` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Exec` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`locals` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`globals` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`FloorDiv` | :attr:`left` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`right` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`For` | :attr:`assign` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`list` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`body` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`else_` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`From` | :attr:`modname` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`names` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Function` | :attr:`decorators` | :class:`Decorators` or ``None`` | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`name` | name used in def, a string | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`argnames` | list of argument names, as | +| | | strings | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`defaults` | list of default values | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`flags` | xxx | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`doc` | doc string, a string or | +| | | ``None`` | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`code` | the body of the function | ++-----------------------+--------------------+---------------------------------+ +| :class:`GenExpr` | :attr:`code` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`GenExprFor` | :attr:`assign` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`iter` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`ifs` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`GenExprIf` | :attr:`test` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`GenExprInner` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`quals` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Getattr` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`attrname` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Global` | :attr:`names` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`If` | :attr:`tests` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`else_` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Import` | :attr:`names` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Invert` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Keyword` | :attr:`name` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Lambda` | :attr:`argnames` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`defaults` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`flags` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`code` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`LeftShift` | :attr:`left` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`right` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`List` | :attr:`nodes` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`ListComp` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`quals` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`ListCompFor` | :attr:`assign` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`list` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`ifs` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`ListCompIf` | :attr:`test` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Mod` | :attr:`left` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`right` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Module` | :attr:`doc` | doc string, a string or | +| | | ``None`` | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`node` | body of the module, a | +| | | :class:`Stmt` | ++-----------------------+--------------------+---------------------------------+ +| :class:`Mul` | :attr:`left` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`right` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Name` | :attr:`name` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Not` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Or` | :attr:`nodes` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Pass` | | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Power` | :attr:`left` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`right` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Print` | :attr:`nodes` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`dest` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Printnl` | :attr:`nodes` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`dest` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Raise` | :attr:`expr1` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`expr2` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`expr3` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Return` | :attr:`value` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`RightShift` | :attr:`left` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`right` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Slice` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`flags` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`lower` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`upper` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Sliceobj` | :attr:`nodes` | list of statements | ++-----------------------+--------------------+---------------------------------+ +| :class:`Stmt` | :attr:`nodes` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Sub` | :attr:`left` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`right` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Subscript` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`flags` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`subs` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`TryExcept` | :attr:`body` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`handlers` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`else_` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`TryFinally` | :attr:`body` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`final` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Tuple` | :attr:`nodes` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`UnaryAdd` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`UnarySub` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`While` | :attr:`test` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`body` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`else_` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`With` | :attr:`expr` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`vars` | | ++-----------------------+--------------------+---------------------------------+ +| | :attr:`body` | | ++-----------------------+--------------------+---------------------------------+ +| :class:`Yield` | :attr:`value` | | ++-----------------------+--------------------+---------------------------------+ + Assignment nodes ---------------- Modified: doctools/trunk/Doc-26/library/contextlib.rst ============================================================================== --- doctools/trunk/Doc-26/library/contextlib.rst (original) +++ doctools/trunk/Doc-26/library/contextlib.rst Thu Aug 2 17:44:40 2007 @@ -82,8 +82,6 @@ :meth:`__exit__` methods should avoid raising exceptions, and in particular they should not re-raise a passed-in exception. -.. _context-closing: - .. function:: closing(thing) Modified: doctools/trunk/Doc-26/library/cookielib.rst ============================================================================== --- doctools/trunk/Doc-26/library/cookielib.rst (original) +++ doctools/trunk/Doc-26/library/cookielib.rst Thu Aug 2 17:44:40 2007 @@ -32,9 +32,8 @@ :mailheader:`Set-Cookie2` headers (eg. ``domain`` and ``expires``) are conventionally referred to as :dfn:`attributes`. To distinguish them from Python attributes, the documentation for this module uses the term - :dfn:`cookie-attribute` instead + :dfn:`cookie-attribute` instead. -. The module defines the following exception: @@ -47,9 +46,8 @@ .. note:: For backwards-compatibility with Python 2.4 (which raised an :exc:`IOError`), - :exc:`LoadError` is a subclass of :exc:`IOError` + :exc:`LoadError` is a subclass of :exc:`IOError`. - . The following classes are provided: @@ -601,7 +599,7 @@ Equivalent to ``DomainStrictNoDots|DomainStrictNonDomain``. -.. _cookie-objects: +.. _cookielib-cookie-objects: Cookie Objects -------------- Added: doctools/trunk/Doc-26/library/idle.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-26/library/idle.rst Thu Aug 2 17:44:40 2007 @@ -0,0 +1,288 @@ +.. _idle: + +Idle +==== + +.. moduleauthor:: Guido van Rossum <guido(a)Python.org> + + +.. % \declaremodule{standard}{idle} +.. % \modulesynopsis{A Python Integrated Development Environment} + +.. index:: + single: Idle + single: Python Editor + single: Integrated Development Environment + +Idle is the Python IDE built with the :mod:`Tkinter` GUI toolkit. + +IDLE has the following features: + +* coded in 100% pure Python, using the :mod:`Tkinter` GUI toolkit + +* cross-platform: works on Windows and Unix (on Mac OS, there are currently + problems with Tcl/Tk) + +* multi-window text editor with multiple undo, Python colorizing and many other + features, e.g. smart indent and call tips + +* Python shell window (a.k.a. interactive interpreter) + +* debugger (not complete, but you can set breakpoints, view and step) + + +Menus +----- + + +File menu +^^^^^^^^^ + +New window + create a new editing window + +Open... + open an existing file + +Open module... + open an existing module (searches sys.path) + +Class browser + show classes and methods in current file + +Path browser + show sys.path directories, modules, classes and methods + +.. index:: + single: Class browser + single: Path browser + +Save + save current window to the associated file (unsaved windows have a \* before and + after the window title) + +Save As... + save current window to new file, which becomes the associated file + +Save Copy As... + save current window to different file without changing the associated file + +Close + close current window (asks to save if unsaved) + +Exit + close all windows and quit IDLE (asks to save if unsaved) + + +Edit menu +^^^^^^^^^ + +Undo + Undo last change to current window (max 1000 changes) + +Redo + Redo last undone change to current window + +Cut + Copy selection into system-wide clipboard; then delete selection + +Copy + Copy selection into system-wide clipboard + +Paste + Insert system-wide clipboard into window + +Select All + Select the entire contents of the edit buffer + +Find... + Open a search dialog box with many options + +Find again + Repeat last search + +Find selection + Search for the string in the selection + +Find in Files... + Open a search dialog box for searching files + +Replace... + Open a search-and-replace dialog box + +Go to line + Ask for a line number and show that line + +Indent region + Shift selected lines right 4 spaces + +Dedent region + Shift selected lines left 4 spaces + +Comment out region + Insert ## in front of selected lines + +Uncomment region + Remove leading # or ## from selected lines + +Tabify region + Turns *leading* stretches of spaces into tabs + +Untabify region + Turn *all* tabs into the right number of spaces + +Expand word + Expand the word you have typed to match another word in the same buffer; repeat + to get a different expansion + +Format Paragraph + Reformat the current blank-line-separated paragraph + +Import module + Import or reload the current module + +Run script + Execute the current file in the __main__ namespace + +.. index:: + single: Import module + single: Run script + + +Windows menu +^^^^^^^^^^^^ + +Zoom Height + toggles the window between normal size (24x80) and maximum height. + +The rest of this menu lists the names of all open windows; select one to bring +it to the foreground (deiconifying it if necessary). + + +Debug menu (in the Python Shell window only) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Go to file/line + look around the insert point for a filename and linenumber, open the file, and + show the line. + +Open stack viewer + show the stack traceback of the last exception + +Debugger toggle + Run commands in the shell under the debugger + +JIT Stack viewer toggle + Open stack viewer on traceback + +.. index:: + single: stack viewer + single: debugger + + +Basic editing and navigation +---------------------------- + +* :kbd:`Backspace` deletes to the left; :kbd:`Del` deletes to the right + +* Arrow keys and :kbd:`Page Up`/:kbd:`Page Down` to move around + +* :kbd:`Home`/:kbd:`End` go to begin/end of line + +* :kbd:`C-Home`/:kbd:`C-End` go to begin/end of file + +* Some :program:`Emacs` bindings may also work, including :kbd:`C-B`, + :kbd:`C-P`, :kbd:`C-A`, :kbd:`C-E`, :kbd:`C-D`, :kbd:`C-L` + + +Automatic indentation +^^^^^^^^^^^^^^^^^^^^^ + +After a block-opening statement, the next line is indented by 4 spaces (in the +Python Shell window by one tab). After certain keywords (break, return etc.) +the next line is dedented. In leading indentation, :kbd:`Backspace` deletes up +to 4 spaces if they are there. :kbd:`Tab` inserts 1-4 spaces (in the Python +Shell window one tab). See also the indent/dedent region commands in the edit +menu. + + +Python Shell window +^^^^^^^^^^^^^^^^^^^ + +* :kbd:`C-C` interrupts executing command + +* :kbd:`C-D` sends end-of-file; closes window if typed at a ``>>>`` prompt + +* :kbd:`Alt-p` retrieves previous command matching what you have typed + +* :kbd:`Alt-n` retrieves next + +* :kbd:`Return` while on any previous command retrieves that command + +* :kbd:`Alt-/` (Expand word) is also useful here + +.. index:: single: indentation + + +Syntax colors +------------- + +The coloring is applied in a background "thread," so you may occasionally see +uncolorized text. To change the color scheme, edit the ``[Colors]`` section in +:file:`config.txt`. + +Python syntax colors: + Keywords + orange + + Strings + green + + Comments + red + + Definitions + blue + +Shell colors: + Console output + brown + + stdout + blue + + stderr + dark green + + stdin + black + + +Command line usage +^^^^^^^^^^^^^^^^^^ + +:: + + idle.py [-c command] [-d] [-e] [-s] [-t title] [arg] ... + + -c command run this command + -d enable debugger + -e edit mode; arguments are files to be edited + -s run $IDLESTARTUP or $PYTHONSTARTUP first + -t title set title of shell window + +If there are arguments: + +#. If :option:`-e` is used, arguments are files opened for editing and + ``sys.argv`` reflects the arguments passed to IDLE itself. + +#. Otherwise, if :option:`-c` is used, all arguments are placed in + ``sys.argv[1:...]``, with ``sys.argv[0]`` set to ``'-c'``. + +#. Otherwise, if neither :option:`-e` nor :option:`-c` is used, the first + argument is a script which is executed with the remaining arguments in + ``sys.argv[1:...]`` and ``sys.argv[0]`` set to the script name. If the script + name is '-', no script is executed but an interactive Python session is started; + the arguments are still available in ``sys.argv``. + + Modified: doctools/trunk/Doc-26/library/index.rst ============================================================================== --- doctools/trunk/Doc-26/library/index.rst (original) +++ doctools/trunk/Doc-26/library/index.rst Thu Aug 2 17:44:40 2007 @@ -51,7 +51,7 @@ ipc.rst internet.rst mm.rst - tkinter.rst + tk.rst i18n.rst frameworks.rst development.rst Modified: doctools/trunk/Doc-26/library/intro.rst ============================================================================== --- doctools/trunk/Doc-26/library/intro.rst (original) +++ doctools/trunk/Doc-26/library/intro.rst Thu Aug 2 17:44:40 2007 @@ -1,5 +1,5 @@ -.. _intro: +.. _library-intro: ************ Introduction Added: doctools/trunk/Doc-26/library/othergui.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-26/library/othergui.rst Thu Aug 2 17:44:40 2007 @@ -0,0 +1,93 @@ +.. _other-gui-packages: + +Other Graphical User Interface Packages +======================================= + +There are an number of extension widget sets to :mod:`Tkinter`. + + +.. seealso:: + + `Python megawidgets <http://pmw.sourceforge.net/>`_ + is a toolkit for building high-level compound widgets in Python using the + :mod:`Tkinter` module. It consists of a set of base classes and a library of + flexible and extensible megawidgets built on this foundation. These megawidgets + include notebooks, comboboxes, selection widgets, paned widgets, scrolled + widgets, dialog windows, etc. Also, with the Pmw.Blt interface to BLT, the + busy, graph, stripchart, tabset and vector commands are be available. + + The initial ideas for Pmw were taken from the Tk ``itcl`` extensions ``[incr + Tk]`` by Michael McLennan and ``[incr Widgets]`` by Mark Ulferts. Several of the + megawidgets are direct translations from the itcl to Python. It offers most of + the range of widgets that ``[incr Widgets]`` does, and is almost as complete as + Tix, lacking however Tix's fast :class:`HList` widget for drawing trees. + + `Tkinter3000 Widget Construction Kit (WCK) <http://tkinter.effbot.org/>`_ + is a library that allows you to write new Tkinter widgets in pure Python. The + WCK framework gives you full control over widget creation, configuration, screen + appearance, and event handling. WCK widgets can be very fast and light-weight, + since they can operate directly on Python data structures, without having to + transfer data through the Tk/Tcl layer. + + .. % + +Other GUI packages are also available for Python: + + +.. seealso:: + + `wxPython <http://www.wxpython.org>`_ + wxPython is a cross-platform GUI toolkit for Python that is built around the + popular `wxWidgets <http://www.wxwidgets.org/>`_ C++ toolkit. It provides a + native look and feel for applications on Windows, Mac OS X, and Unix systems by + using each platform's native widgets where ever possible, (GTK+ on Unix-like + systems). In addition to an extensive set of widgets, wxPython provides classes + for online documentation and context sensitive help, printing, HTML viewing, + low-level device context drawing, drag and drop, system clipboard access, an + XML-based resource format and more, including an ever growing library of user- + contributed modules. Both the wxWidgets and wxPython projects are under active + development and continuous improvement, and have active and helpful user and + developer communities. + + `wxPython in Action <http://www.amazon.com/exec/obidos/ASIN/1932394621>`_ + The wxPython book, by Noel Rappin and Robin Dunn. + + PyQt + PyQt is a :program:`sip`\ -wrapped binding to the Qt toolkit. Qt is an + extensive C++ GUI toolkit that is available for Unix, Windows and Mac OS X. + :program:`sip` is a tool for generating bindings for C++ libraries as Python + classes, and is specifically designed for Python. An online manual is available + at http://www.opendocspublishing.com/pyqt/ (errata are located at + http://www.valdyas.org/python/book.html). + + `PyKDE <http://www.riverbankcomputing.co.uk/pykde/index.php>`_ + PyKDE is a :program:`sip`\ -wrapped interface to the KDE desktop libraries. KDE + is a desktop environment for Unix computers; the graphical components are based + on Qt. + + `FXPy <http://fxpy.sourceforge.net/>`_ + is a Python extension module which provides an interface to the `FOX + <http://www.cfdrc.com/FOX/fox.html>`_ GUI. FOX is a C++ based Toolkit for + developing Graphical User Interfaces easily and effectively. It offers a wide, + and growing, collection of Controls, and provides state of the art facilities + such as drag and drop, selection, as well as OpenGL widgets for 3D graphical + manipulation. FOX also implements icons, images, and user-convenience features + such as status line help, and tooltips. + + Even though FOX offers a large collection of controls already, FOX leverages C++ + to allow programmers to easily build additional Controls and GUI elements, + simply by taking existing controls, and creating a derived class which simply + adds or redefines the desired behavior. + + `PyGTK <http://www.daa.com.au/~james/software/pygtk/>`_ + is a set of bindings for the `GTK <http://www.gtk.org/>`_ widget set. It + provides an object oriented interface that is slightly higher level than the C + one. It automatically does all the type casting and reference counting that you + would have to do normally with the C API. There are also `bindings + <http://www.daa.com.au/~james/gnome/>`_ to `GNOME <http://www.gnome.org>`_, and + a `tutorial + <http://laguna.fmedic.unam.mx/~daniel/pygtutorial/pygtutorial/index.html>`_ is + available. + +.. % XXX Reference URLs that compare the different UI packages + Added: doctools/trunk/Doc-26/library/scrolledtext.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-26/library/scrolledtext.rst Thu Aug 2 17:44:40 2007 @@ -0,0 +1,32 @@ +:mod:`ScrolledText` --- Scrolled Text Widget +============================================ + +.. module:: ScrolledText + :platform: Tk + :synopsis: Text widget with a vertical scroll bar. +.. sectionauthor:: Fred L. Drake, Jr. <fdrake(a)acm.org> + + +The :mod:`ScrolledText` module provides a class of the same name which +implements a basic text widget which has a vertical scroll bar configured to do +the "right thing." Using the :class:`ScrolledText` class is a lot easier than +setting up a text widget and scroll bar directly. The constructor is the same +as that of the :class:`Tkinter.Text` class. + +The text widget and scrollbar are packed together in a :class:`Frame`, and the +methods of the :class:`Grid` and :class:`Pack` geometry managers are acquired +from the :class:`Frame` object. This allows the :class:`ScrolledText` widget to +be used directly to achieve most normal geometry management behavior. + +Should more specific control be necessary, the following attributes are +available: + + +.. attribute:: ScrolledText.frame + + The frame which surrounds the text and scroll bar widgets. + + +.. attribute:: ScrolledText.vbar + + The scroll bar widget. Modified: doctools/trunk/Doc-26/library/sqlite3.rst ============================================================================== --- doctools/trunk/Doc-26/library/sqlite3.rst (original) +++ doctools/trunk/Doc-26/library/sqlite3.rst Thu Aug 2 17:44:40 2007 @@ -148,9 +148,8 @@ for the lock to go away until raising an exception. The default for the timeout parameter is 5.0 (five seconds). - For the *isolation_level* parameter, please see the :attr:`isolation_level` - property of :class:`Connection` objects in section - :ref:`sqlite3-connection-isolationlevel`. + For the *isolation_level* parameter, please see the + :attr:`Connection.isolation_level` property of :class:`Connection` objects. SQLite natively supports only the types TEXT, INTEGER, FLOAT, BLOB and NULL. If you want to use other types you must add support for them yourself. The @@ -221,9 +220,6 @@ A :class:`Connection` instance has the following attributes and methods: -.. _sqlite3-connection-isolationlevel: - - .. attribute:: Connection.isolation_level Get or set the current isolation level. None for autocommit mode or one of Modified: doctools/trunk/Doc-26/library/stdtypes.rst ============================================================================== --- doctools/trunk/Doc-26/library/stdtypes.rst (original) +++ doctools/trunk/Doc-26/library/stdtypes.rst Thu Aug 2 17:44:40 2007 @@ -1,5 +1,5 @@ -.. _types: +.. _bltin-types: ************** Built-in Types @@ -120,7 +120,7 @@ interpreted as ``not (a == b)``, and ``a == not b`` is a syntax error. -.. _comparisons: +.. _stdcomparisons: Comparisons =========== @@ -1781,9 +1781,8 @@ Not all "file-like" types in Python support use as a context manager for the :keyword:`with` statement. If your code is intended to work with any file-like - object, you can use the :func:`closing` function in the :mod:`contextlib` module - instead of using the object directly. See section :ref:`context-closing` for - details. + object, you can use the function :func:`contextlib.closing` instead of using + the object directly. .. method:: file.flush() Modified: doctools/trunk/Doc-26/library/strings.rst ============================================================================== --- doctools/trunk/Doc-26/library/strings.rst (original) +++ doctools/trunk/Doc-26/library/strings.rst Thu Aug 2 17:44:40 2007 @@ -1,5 +1,5 @@ -.. _strings: +.. _stringservices: *************** String Services Modified: doctools/trunk/Doc-26/library/tarfile.rst ============================================================================== --- doctools/trunk/Doc-26/library/tarfile.rst (original) +++ doctools/trunk/Doc-26/library/tarfile.rst Thu Aug 2 17:44:40 2007 @@ -1,3 +1,4 @@ +.. _tarfile-mod: :mod:`tarfile` --- Read and write tar archive files =================================================== @@ -286,7 +287,7 @@ .. method:: TarFile.open(...) Alternative constructor. The :func:`open` function on module level is actually a - shortcut to this classmethod. See section :ref:`module-tarfile` for details. + shortcut to this classmethod. See section :ref:`tarfile-mod` for details. .. method:: TarFile.getmember(name) Added: doctools/trunk/Doc-26/library/tix.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-26/library/tix.rst Thu Aug 2 17:44:40 2007 @@ -0,0 +1,602 @@ +:mod:`Tix` --- Extension widgets for Tk +======================================= + +.. module:: Tix + :synopsis: Tk Extension Widgets for Tkinter +.. sectionauthor:: Mike Clarkson <mikeclarkson(a)users.sourceforge.net> + + +.. index:: single: Tix + +The :mod:`Tix` (Tk Interface Extension) module provides an additional rich set +of widgets. Although the standard Tk library has many useful widgets, they are +far from complete. The :mod:`Tix` library provides most of the commonly needed +widgets that are missing from standard Tk: :class:`HList`, :class:`ComboBox`, +:class:`Control` (a.k.a. SpinBox) and an assortment of scrollable widgets. +:mod:`Tix` also includes many more widgets that are generally useful in a wide +range of applications: :class:`NoteBook`, :class:`FileEntry`, +:class:`PanedWindow`, etc; there are more than 40 of them. + +With all these new widgets, you can introduce new interaction techniques into +applications, creating more useful and more intuitive user interfaces. You can +design your application by choosing the most appropriate widgets to match the +special needs of your application and users. + + +.. seealso:: + + `Tix Homepage <http://tix.sourceforge.net/>`_ + The home page for :mod:`Tix`. This includes links to additional documentation + and downloads. + + `Tix Man Pages <http://tix.sourceforge.net/dist/current/man/>`_ + On-line version of the man pages and reference material. + + `Tix Programming Guide <http://tix.sourceforge.net/dist/current/docs/tix-book/tix.book.html>`_ + On-line version of the programmer's reference material. + + `Tix Development Applications <http://tix.sourceforge.net/Tide/>`_ + Tix applications for development of Tix and Tkinter programs. Tide applications + work under Tk or Tkinter, and include :program:`TixInspect`, an inspector to + remotely modify and debug Tix/Tk/Tkinter applications. + + +Using Tix +--------- + + +.. class:: Tix(screenName[, baseName[, className]]) + + Toplevel widget of Tix which represents mostly the main window of an + application. It has an associated Tcl interpreter. + + Classes in the :mod:`Tix` module subclasses the classes in the :mod:`Tkinter` + module. The former imports the latter, so to use :mod:`Tix` with Tkinter, all + you need to do is to import one module. In general, you can just import + :mod:`Tix`, and replace the toplevel call to :class:`Tkinter.Tk` with + :class:`Tix.Tk`:: + + import Tix + from Tkconstants import * + root = Tix.Tk() + +To use :mod:`Tix`, you must have the :mod:`Tix` widgets installed, usually +alongside your installation of the Tk widgets. To test your installation, try +the following:: + + import Tix + root = Tix.Tk() + root.tk.eval('package require Tix') + +If this fails, you have a Tk installation problem which must be resolved before +proceeding. Use the environment variable :envvar:`TIX_LIBRARY` to point to the +installed :mod:`Tix` library directory, and make sure you have the dynamic +object library (:file:`tix8183.dll` or :file:`libtix8183.so`) in the same +directory that contains your Tk dynamic object library (:file:`tk8183.dll` or +:file:`libtk8183.so`). The directory with the dynamic object library should also +have a file called :file:`pkgIndex.tcl` (case sensitive), which contains the +line:: + + package ifneeded Tix 8.1 [list load "[file join $dir tix8183.dll]" Tix] + +.. % $ <-- bow to font-lock + + +Tix Widgets +----------- + +`Tix <http://tix.sourceforge.net/dist/current/man/html/TixCmd/TixIntro.htm>`_ +introduces over 40 widget classes to the :mod:`Tkinter` repertoire. There is a +demo of all the :mod:`Tix` widgets in the :file:`Demo/tix` directory of the +standard distribution. + +.. % The Python sample code is still being added to Python, hence commented out + + +Basic Widgets +^^^^^^^^^^^^^ + + +.. class:: Balloon() + + A `Balloon + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixBalloon.htm>`_ that + pops up over a widget to provide help. When the user moves the cursor inside a + widget to which a Balloon widget has been bound, a small pop-up window with a + descriptive message will be shown on the screen. + +.. % Python Demo of: +.. % \ulink{Balloon}{http://tix.sourceforge.net/dist/current/demos/samples/Balloon.tcl} + + +.. class:: ButtonBox() + + The `ButtonBox + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixButtonBox.htm>`_ + widget creates a box of buttons, such as is commonly used for ``Ok Cancel``. + +.. % Python Demo of: +.. % \ulink{ButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/BtnBox.tcl} + + +.. class:: ComboBox() + + The `ComboBox + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixComboBox.htm>`_ + widget is similar to the combo box control in MS Windows. The user can select a + choice by either typing in the entry subwdget or selecting from the listbox + subwidget. + +.. % Python Demo of: +.. % \ulink{ComboBox}{http://tix.sourceforge.net/dist/current/demos/samples/ComboBox.tcl} + + +.. class:: Control() + + The `Control + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixControl.htm>`_ + widget is also known as the :class:`SpinBox` widget. The user can adjust the + value by pressing the two arrow buttons or by entering the value directly into + the entry. The new value will be checked against the user-defined upper and + lower limits. + +.. % Python Demo of: +.. % \ulink{Control}{http://tix.sourceforge.net/dist/current/demos/samples/Control.tcl} + + +.. class:: LabelEntry() + + The `LabelEntry + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelEntry.htm>`_ + widget packages an entry widget and a label into one mega widget. It can be used + be used to simplify the creation of "entry-form" type of interface. + +.. % Python Demo of: +.. % \ulink{LabelEntry}{http://tix.sourceforge.net/dist/current/demos/samples/LabEntry.tcl} + + +.. class:: LabelFrame() + + The `LabelFrame + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelFrame.htm>`_ + widget packages a frame widget and a label into one mega widget. To create + widgets inside a LabelFrame widget, one creates the new widgets relative to the + :attr:`frame` subwidget and manage them inside the :attr:`frame` subwidget. + +.. % Python Demo of: +.. % \ulink{LabelFrame}{http://tix.sourceforge.net/dist/current/demos/samples/LabFrame.tcl} + + +.. class:: Meter() + + The `Meter + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixMeter.htm>`_ widget + can be used to show the progress of a background job which may take a long time + to execute. + +.. % Python Demo of: +.. % \ulink{Meter}{http://tix.sourceforge.net/dist/current/demos/samples/Meter.tcl} + + +.. class:: OptionMenu() + + The `OptionMenu + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixOptionMenu.htm>`_ + creates a menu button of options. + +.. % Python Demo of: +.. % \ulink{OptionMenu}{http://tix.sourceforge.net/dist/current/demos/samples/OptMenu.tcl} + + +.. class:: PopupMenu() + + The `PopupMenu + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPopupMenu.htm>`_ + widget can be used as a replacement of the ``tk_popup`` command. The advantage + of the :mod:`Tix` :class:`PopupMenu` widget is it requires less application code + to manipulate. + +.. % Python Demo of: +.. % \ulink{PopupMenu}{http://tix.sourceforge.net/dist/current/demos/samples/PopMenu.tcl} + + +.. class:: Select() + + The `Select + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixSelect.htm>`_ widget + is a container of button subwidgets. It can be used to provide radio-box or + check-box style of selection options for the user. + +.. % Python Demo of: +.. % \ulink{Select}{http://tix.sourceforge.net/dist/current/demos/samples/Select.tcl} + + +.. class:: StdButtonBox() + + The `StdButtonBox + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixStdButtonBox.htm>`_ + widget is a group of standard buttons for Motif-like dialog boxes. + +.. % Python Demo of: +.. % \ulink{StdButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/StdBBox.tcl} + + +File Selectors +^^^^^^^^^^^^^^ + + +.. class:: DirList() + + The `DirList + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirList.htm>`_ + widget displays a list view of a directory, its previous directories and its + sub-directories. The user can choose one of the directories displayed in the + list or change to another directory. + +.. % Python Demo of: +.. % \ulink{DirList}{http://tix.sourceforge.net/dist/current/demos/samples/DirList.tcl} + + +.. class:: DirTree() + + The `DirTree + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirTree.htm>`_ + widget displays a tree view of a directory, its previous directories and its + sub-directories. The user can choose one of the directories displayed in the + list or change to another directory. + +.. % Python Demo of: +.. % \ulink{DirTree}{http://tix.sourceforge.net/dist/current/demos/samples/DirTree.tcl} + + +.. class:: DirSelectDialog() + + The `DirSelectDialog + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirSelectDialog.…>`_ + widget presents the directories in the file system in a dialog window. The user + can use this dialog window to navigate through the file system to select the + desired directory. + +.. % Python Demo of: +.. % \ulink{DirSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/DirDlg.tcl} + + +.. class:: DirSelectBox() + + The :class:`DirSelectBox` is similar to the standard Motif(TM) directory- + selection box. It is generally used for the user to choose a directory. + DirSelectBox stores the directories mostly recently selected into a ComboBox + widget so that they can be quickly selected again. + + +.. class:: ExFileSelectBox() + + The `ExFileSelectBox + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixExFileSelectBox.…>`_ + widget is usually embedded in a tixExFileSelectDialog widget. It provides an + convenient method for the user to select files. The style of the + :class:`ExFileSelectBox` widget is very similar to the standard file dialog on + MS Windows 3.1. + +.. % Python Demo of: +.. % \ulink{ExFileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/EFileDlg.tcl} + + +.. class:: FileSelectBox() + + The `FileSelectBox + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileSelectBox.htm>`_ + is similar to the standard Motif(TM) file-selection box. It is generally used + for the user to choose a file. FileSelectBox stores the files mostly recently + selected into a :class:`ComboBox` widget so that they can be quickly selected + again. + +.. % Python Demo of: +.. % \ulink{FileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/FileDlg.tcl} + + +.. class:: FileEntry() + + The `FileEntry + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileEntry.htm>`_ + widget can be used to input a filename. The user can type in the filename + manually. Alternatively, the user can press the button widget that sits next to + the entry, which will bring up a file selection dialog. + +.. % Python Demo of: +.. % \ulink{FileEntry}{http://tix.sourceforge.net/dist/current/demos/samples/FileEnt.tcl} + + +Hierachical ListBox +^^^^^^^^^^^^^^^^^^^ + + +.. class:: HList() + + The `HList + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixHList.htm>`_ widget + can be used to display any data that have a hierarchical structure, for example, + file system directory trees. The list entries are indented and connected by + branch lines according to their places in the hierarchy. + +.. % Python Demo of: +.. % \ulink{HList}{http://tix.sourceforge.net/dist/current/demos/samples/HList1.tcl} + + +.. class:: CheckList() + + The `CheckList + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixCheckList.htm>`_ + widget displays a list of items to be selected by the user. CheckList acts + similarly to the Tk checkbutton or radiobutton widgets, except it is capable of + handling many more items than checkbuttons or radiobuttons. + +.. % Python Demo of: +.. % \ulink{ CheckList}{http://tix.sourceforge.net/dist/current/demos/samples/ChkList.tc… +.. % Python Demo of: +.. % \ulink{ScrolledHList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList.tcl} +.. % Python Demo of: +.. % \ulink{ScrolledHList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList2.tcl} + + +.. class:: Tree() + + The `Tree + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTree.htm>`_ widget + can be used to display hierarchical data in a tree form. The user can adjust the + view of the tree by opening or closing parts of the tree. + +.. % Python Demo of: +.. % \ulink{Tree}{http://tix.sourceforge.net/dist/current/demos/samples/Tree.tcl} +.. % Python Demo of: +.. % \ulink{Tree (Dynamic)}{http://tix.sourceforge.net/dist/current/demos/samples/DynTree.tcl} + + +Tabular ListBox +^^^^^^^^^^^^^^^ + + +.. class:: TList() + + The `TList + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTList.htm>`_ widget + can be used to display data in a tabular format. The list entries of a + :class:`TList` widget are similar to the entries in the Tk listbox widget. The + main differences are (1) the :class:`TList` widget can display the list entries + in a two dimensional format and (2) you can use graphical images as well as + multiple colors and fonts for the list entries. + +.. % Python Demo of: +.. % \ulink{ScrolledTList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/STList1.tcl} +.. % Python Demo of: +.. % \ulink{ScrolledTList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/STList2.tcl} +.. % Grid has yet to be added to Python +.. % \subsubsection{Grid Widget} +.. % Python Demo of: +.. % \ulink{Simple Grid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid0.tcl} +.. % Python Demo of: +.. % \ulink{ScrolledGrid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid1.tcl} +.. % Python Demo of: +.. % \ulink{Editable Grid}{http://tix.sourceforge.net/dist/current/demos/samples/EditGrid.tcl} + + +Manager Widgets +^^^^^^^^^^^^^^^ + + +.. class:: PanedWindow() + + The `PanedWindow + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPanedWindow.htm>`_ + widget allows the user to interactively manipulate the sizes of several panes. + The panes can be arranged either vertically or horizontally. The user changes + the sizes of the panes by dragging the resize handle between two panes. + +.. % Python Demo of: +.. % \ulink{PanedWindow}{http://tix.sourceforge.net/dist/current/demos/samples/PanedWin.tcl} + + +.. class:: ListNoteBook() + + The `ListNoteBook + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixListNoteBook.htm>`_ + widget is very similar to the :class:`TixNoteBook` widget: it can be used to + display many windows in a limited space using a notebook metaphor. The notebook + is divided into a stack of pages (windows). At one time only one of these pages + can be shown. The user can navigate through these pages by choosing the name of + the desired page in the :attr:`hlist` subwidget. + +.. % Python Demo of: +.. % \ulink{ListNoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/ListNBK.tcl} + + +.. class:: NoteBook() + + The `NoteBook + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixNoteBook.htm>`_ + widget can be used to display many windows in a limited space using a notebook + metaphor. The notebook is divided into a stack of pages. At one time only one of + these pages can be shown. The user can navigate through these pages by choosing + the visual "tabs" at the top of the NoteBook widget. + +.. % Python Demo of: +.. % \ulink{NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/NoteBook.tcl} + +.. % \subsubsection{Scrolled Widgets} +.. % Python Demo of: +.. % \ulink{ScrolledListBox}{http://tix.sourceforge.net/dist/current/demos/samples/SListBox.tcl} +.. % Python Demo of: +.. % \ulink{ScrolledText}{http://tix.sourceforge.net/dist/current/demos/samples/SText.tcl} +.. % Python Demo of: +.. % \ulink{ScrolledWindow}{http://tix.sourceforge.net/dist/current/demos/samples/SWindow.tcl} +.. % Python Demo of: +.. % \ulink{Canvas Object View}{http://tix.sourceforge.net/dist/current/demos/samples/CObjView.tcl} + + +Image Types +^^^^^^^^^^^ + +The :mod:`Tix` module adds: + +* `pixmap <http://tix.sourceforge.net/dist/current/man/html/TixCmd/pixmap.htm>`_ + capabilities to all :mod:`Tix` and :mod:`Tkinter` widgets to create color images + from XPM files. + + .. % Python Demo of: + .. % \ulink{XPM Image In Button}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm.tcl} + .. % Python Demo of: + .. % \ulink{XPM Image In Menu}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm1.tcl} + +* `Compound + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/compound.htm>`_ image + types can be used to create images that consists of multiple horizontal lines; + each line is composed of a series of items (texts, bitmaps, images or spaces) + arranged from left to right. For example, a compound image can be used to + display a bitmap and a text string simultaneously in a Tk :class:`Button` + widget. + + .. % Python Demo of: + .. % \ulink{Compound Image In Buttons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg.tcl} + .. % Python Demo of: + .. % \ulink{Compound Image In NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg2.tcl} + .. % Python Demo of: + .. % \ulink{Compound Image Notebook Color Tabs}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg4.tcl} + .. % Python Demo of: + .. % \ulink{Compound Image Icons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg3.tcl} + + +Miscellaneous Widgets +^^^^^^^^^^^^^^^^^^^^^ + + +.. class:: InputOnly() + + The `InputOnly + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixInputOnly.htm>`_ + widgets are to accept inputs from the user, which can be done with the ``bind`` + command (Unix only). + + +Form Geometry Manager +^^^^^^^^^^^^^^^^^^^^^ + +In addition, :mod:`Tix` augments :mod:`Tkinter` by providing: + + +.. class:: Form() + + The `Form + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixForm.htm>`_ geometry + manager based on attachment rules for all Tk widgets. + +.. % begin{latexonly} +.. % \subsection{Tix Class Structure} +.. % +.. % \begin{figure}[hbtp] +.. % \centerline{\epsfig{file=hierarchy.png,width=.9\textwidth}} +.. % \vspace{.5cm} +.. % \caption{The Class Hierarchy of Tix Widgets} +.. % \end{figure} +.. % end{latexonly} + + +Tix Commands +------------ + + +.. class:: tixCommand() + + The `tix commands + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tix.htm>`_ provide + access to miscellaneous elements of :mod:`Tix`'s internal state and the + :mod:`Tix` application context. Most of the information manipulated by these + methods pertains to the application as a whole, or to a screen or display, + rather than to a particular window. + + To view the current settings, the common usage is:: + + import Tix + root = Tix.Tk() + print root.tix_configure() + + +.. method:: tixCommand.tix_configure([cnf,] **kw) + + Query or modify the configuration options of the Tix application context. If no + option is specified, returns a dictionary all of the available options. If + option is specified with no value, then the method returns a list describing the + one named option (this list will be identical to the corresponding sublist of + the value returned if no option is specified). If one or more option-value + pairs are specified, then the method modifies the given option(s) to have the + given value(s); in this case the method returns an empty string. Option may be + any of the configuration options. + + +.. method:: tixCommand.tix_cget(option) + + Returns the current value of the configuration option given by *option*. Option + may be any of the configuration options. + + +.. method:: tixCommand.tix_getbitmap(name) + + Locates a bitmap file of the name ``name.xpm`` or ``name`` in one of the bitmap + directories (see the :meth:`tix_addbitmapdir` method). By using + :meth:`tix_getbitmap`, you can avoid hard coding the pathnames of the bitmap + files in your application. When successful, it returns the complete pathname of + the bitmap file, prefixed with the character ``@``. The returned value can be + used to configure the ``bitmap`` option of the Tk and Tix widgets. + + +.. method:: tixCommand.tix_addbitmapdir(directory) + + Tix maintains a list of directories under which the :meth:`tix_getimage` and + :meth:`tix_getbitmap` methods will search for image files. The standard bitmap + directory is :file:`$TIX_LIBRARY/bitmaps`. The :meth:`tix_addbitmapdir` method + adds *directory* into this list. By using this method, the image files of an + applications can also be located using the :meth:`tix_getimage` or + :meth:`tix_getbitmap` method. + + +.. method:: tixCommand.tix_filedialog([dlgclass]) + + Returns the file selection dialog that may be shared among different calls from + this application. This method will create a file selection dialog widget when + it is called the first time. This dialog will be returned by all subsequent + calls to :meth:`tix_filedialog`. An optional dlgclass parameter can be passed + as a string to specified what type of file selection dialog widget is desired. + Possible options are ``tix``, ``FileSelectDialog`` or ``tixExFileSelectDialog``. + + +.. method:: tixCommand.tix_getimage(self, name) + + Locates an image file of the name :file:`name.xpm`, :file:`name.xbm` or + :file:`name.ppm` in one of the bitmap directories (see the + :meth:`tix_addbitmapdir` method above). If more than one file with the same name + (but different extensions) exist, then the image type is chosen according to the + depth of the X display: xbm images are chosen on monochrome displays and color + images are chosen on color displays. By using :meth:`tix_getimage`, you can + avoid hard coding the pathnames of the image files in your application. When + successful, this method returns the name of the newly created image, which can + be used to configure the ``image`` option of the Tk and Tix widgets. + + +.. method:: tixCommand.tix_option_get(name) + + Gets the options maintained by the Tix scheme mechanism. + + +.. method:: tixCommand.tix_resetoptions(newScheme, newFontSet[, newScmPrio]) + + Resets the scheme and fontset of the Tix application to *newScheme* and + *newFontSet*, respectively. This affects only those widgets created after this + call. Therefore, it is best to call the resetoptions method before the creation + of any widgets in a Tix application. + + The optional parameter *newScmPrio* can be given to reset the priority level of + the Tk options set by the Tix schemes. + + Because of the way Tk handles the X option database, after Tix has been has + imported and inited, it is not possible to reset the color schemes and font sets + using the :meth:`tix_config` method. Instead, the :meth:`tix_resetoptions` + method must be used. Added: doctools/trunk/Doc-26/library/tk.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-26/library/tk.rst Thu Aug 2 17:44:40 2007 @@ -0,0 +1,40 @@ +.. _tkinter: + +********************************* +Graphical User Interfaces with Tk +********************************* + +.. index:: + single: GUI + single: Graphical User Interface + single: Tkinter + single: Tk + +Tk/Tcl has long been an integral part of Python. It provides a robust and +platform independent windowing toolkit, that is available to Python programmers +using the :mod:`Tkinter` module, and its extension, the :mod:`Tix` module. + +The :mod:`Tkinter` module is a thin object-oriented layer on top of Tcl/Tk. To +use :mod:`Tkinter`, you don't need to write Tcl code, but you will need to +consult the Tk documentation, and occasionally the Tcl documentation. +:mod:`Tkinter` is a set of wrappers that implement the Tk widgets as Python +classes. In addition, the internal module :mod:`_tkinter` provides a threadsafe +mechanism which allows Python and Tcl to interact. + +Tk is not the only GUI for Python; see section :ref:`other-gui-packages` for +more information on other GUI toolkits for Python. + +.. toctree:: + + tkinter.rst + tix.rst + scrolledtext.rst + turtle.rst + idle.rst + othergui.rst + +.. % Other sections I have in mind are +.. % Tkinter internals +.. % Freezing Tkinter applications + + Modified: doctools/trunk/Doc-26/library/tkinter.rst ============================================================================== --- doctools/trunk/Doc-26/library/tkinter.rst (original) +++ doctools/trunk/Doc-26/library/tkinter.rst Thu Aug 2 17:44:40 2007 @@ -1,38 +1,3 @@ - -.. _tkinter: - -********************************* -Graphical User Interfaces with Tk -********************************* - -.. index:: - single: GUI - single: Graphical User Interface - single: Tkinter - single: Tk - -Tk/Tcl has long been an integral part of Python. It provides a robust and -platform independent windowing toolkit, that is available to Python programmers -using the :mod:`Tkinter` module, and its extension, the :mod:`Tix` module. - -The :mod:`Tkinter` module is a thin object-oriented layer on top of Tcl/Tk. To -use :mod:`Tkinter`, you don't need to write Tcl code, but you will need to -consult the Tk documentation, and occasionally the Tcl documentation. -:mod:`Tkinter` is a set of wrappers that implement the Tk widgets as Python -classes. In addition, the internal module :mod:`_tkinter` provides a threadsafe -mechanism which allows Python and Tcl to interact. - -Tk is not the only GUI for Python; see section :ref:`other-gui-packages` for -more information on other GUI toolkits for Python. - -.. % Other sections I have in mind are -.. % Tkinter internals -.. % Freezing Tkinter applications - - -.. toctree:: - - :mod:`Tkinter` --- Python interface to Tcl/Tk ============================================= @@ -873,1024 +838,3 @@ deleted, the image data is deleted as well, and Tk will display an empty box wherever the image was used. - -:mod:`Tix` --- Extension widgets for Tk -======================================= - -.. module:: Tix - :synopsis: Tk Extension Widgets for Tkinter -.. sectionauthor:: Mike Clarkson <mikeclarkson(a)users.sourceforge.net> - - -.. index:: single: Tix - -The :mod:`Tix` (Tk Interface Extension) module provides an additional rich set -of widgets. Although the standard Tk library has many useful widgets, they are -far from complete. The :mod:`Tix` library provides most of the commonly needed -widgets that are missing from standard Tk: :class:`HList`, :class:`ComboBox`, -:class:`Control` (a.k.a. SpinBox) and an assortment of scrollable widgets. -:mod:`Tix` also includes many more widgets that are generally useful in a wide -range of applications: :class:`NoteBook`, :class:`FileEntry`, -:class:`PanedWindow`, etc; there are more than 40 of them. - -With all these new widgets, you can introduce new interaction techniques into -applications, creating more useful and more intuitive user interfaces. You can -design your application by choosing the most appropriate widgets to match the -special needs of your application and users. - - -.. seealso:: - - `Tix Homepage <http://tix.sourceforge.net/>`_ - The home page for :mod:`Tix`. This includes links to additional documentation - and downloads. - - `Tix Man Pages <http://tix.sourceforge.net/dist/current/man/>`_ - On-line version of the man pages and reference material. - - `Tix Programming Guide <http://tix.sourceforge.net/dist/current/docs/tix-book/tix.book.html>`_ - On-line version of the programmer's reference material. - - `Tix Development Applications <http://tix.sourceforge.net/Tide/>`_ - Tix applications for development of Tix and Tkinter programs. Tide applications - work under Tk or Tkinter, and include :program:`TixInspect`, an inspector to - remotely modify and debug Tix/Tk/Tkinter applications. - - -Using Tix ---------- - - -.. class:: Tix(screenName[, baseName[, className]]) - - Toplevel widget of Tix which represents mostly the main window of an - application. It has an associated Tcl interpreter. - - Classes in the :mod:`Tix` module subclasses the classes in the :mod:`Tkinter` - module. The former imports the latter, so to use :mod:`Tix` with Tkinter, all - you need to do is to import one module. In general, you can just import - :mod:`Tix`, and replace the toplevel call to :class:`Tkinter.Tk` with - :class:`Tix.Tk`:: - - import Tix - from Tkconstants import * - root = Tix.Tk() - -To use :mod:`Tix`, you must have the :mod:`Tix` widgets installed, usually -alongside your installation of the Tk widgets. To test your installation, try -the following:: - - import Tix - root = Tix.Tk() - root.tk.eval('package require Tix') - -If this fails, you have a Tk installation problem which must be resolved before -proceeding. Use the environment variable :envvar:`TIX_LIBRARY` to point to the -installed :mod:`Tix` library directory, and make sure you have the dynamic -object library (:file:`tix8183.dll` or :file:`libtix8183.so`) in the same -directory that contains your Tk dynamic object library (:file:`tk8183.dll` or -:file:`libtk8183.so`). The directory with the dynamic object library should also -have a file called :file:`pkgIndex.tcl` (case sensitive), which contains the -line:: - - package ifneeded Tix 8.1 [list load "[file join $dir tix8183.dll]" Tix] - -.. % $ <-- bow to font-lock - - -Tix Widgets ------------ - -`Tix <http://tix.sourceforge.net/dist/current/man/html/TixCmd/TixIntro.htm>`_ -introduces over 40 widget classes to the :mod:`Tkinter` repertoire. There is a -demo of all the :mod:`Tix` widgets in the :file:`Demo/tix` directory of the -standard distribution. - -.. % The Python sample code is still being added to Python, hence commented out - - -Basic Widgets -^^^^^^^^^^^^^ - - -.. class:: Balloon() - - A `Balloon - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixBalloon.htm>`_ that - pops up over a widget to provide help. When the user moves the cursor inside a - widget to which a Balloon widget has been bound, a small pop-up window with a - descriptive message will be shown on the screen. - -.. % Python Demo of: -.. % \ulink{Balloon}{http://tix.sourceforge.net/dist/current/demos/samples/Balloon.tcl} - - -.. class:: ButtonBox() - - The `ButtonBox - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixButtonBox.htm>`_ - widget creates a box of buttons, such as is commonly used for ``Ok Cancel``. - -.. % Python Demo of: -.. % \ulink{ButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/BtnBox.tcl} - - -.. class:: ComboBox() - - The `ComboBox - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixComboBox.htm>`_ - widget is similar to the combo box control in MS Windows. The user can select a - choice by either typing in the entry subwdget or selecting from the listbox - subwidget. - -.. % Python Demo of: -.. % \ulink{ComboBox}{http://tix.sourceforge.net/dist/current/demos/samples/ComboBox.tcl} - - -.. class:: Control() - - The `Control - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixControl.htm>`_ - widget is also known as the :class:`SpinBox` widget. The user can adjust the - value by pressing the two arrow buttons or by entering the value directly into - the entry. The new value will be checked against the user-defined upper and - lower limits. - -.. % Python Demo of: -.. % \ulink{Control}{http://tix.sourceforge.net/dist/current/demos/samples/Control.tcl} - - -.. class:: LabelEntry() - - The `LabelEntry - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelEntry.htm>`_ - widget packages an entry widget and a label into one mega widget. It can be used - be used to simplify the creation of "entry-form" type of interface. - -.. % Python Demo of: -.. % \ulink{LabelEntry}{http://tix.sourceforge.net/dist/current/demos/samples/LabEntry.tcl} - - -.. class:: LabelFrame() - - The `LabelFrame - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelFrame.htm>`_ - widget packages a frame widget and a label into one mega widget. To create - widgets inside a LabelFrame widget, one creates the new widgets relative to the - :attr:`frame` subwidget and manage them inside the :attr:`frame` subwidget. - -.. % Python Demo of: -.. % \ulink{LabelFrame}{http://tix.sourceforge.net/dist/current/demos/samples/LabFrame.tcl} - - -.. class:: Meter() - - The `Meter - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixMeter.htm>`_ widget - can be used to show the progress of a background job which may take a long time - to execute. - -.. % Python Demo of: -.. % \ulink{Meter}{http://tix.sourceforge.net/dist/current/demos/samples/Meter.tcl} - - -.. class:: OptionMenu() - - The `OptionMenu - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixOptionMenu.htm>`_ - creates a menu button of options. - -.. % Python Demo of: -.. % \ulink{OptionMenu}{http://tix.sourceforge.net/dist/current/demos/samples/OptMenu.tcl} - - -.. class:: PopupMenu() - - The `PopupMenu - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPopupMenu.htm>`_ - widget can be used as a replacement of the ``tk_popup`` command. The advantage - of the :mod:`Tix` :class:`PopupMenu` widget is it requires less application code - to manipulate. - -.. % Python Demo of: -.. % \ulink{PopupMenu}{http://tix.sourceforge.net/dist/current/demos/samples/PopMenu.tcl} - - -.. class:: Select() - - The `Select - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixSelect.htm>`_ widget - is a container of button subwidgets. It can be used to provide radio-box or - check-box style of selection options for the user. - -.. % Python Demo of: -.. % \ulink{Select}{http://tix.sourceforge.net/dist/current/demos/samples/Select.tcl} - - -.. class:: StdButtonBox() - - The `StdButtonBox - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixStdButtonBox.htm>`_ - widget is a group of standard buttons for Motif-like dialog boxes. - -.. % Python Demo of: -.. % \ulink{StdButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/StdBBox.tcl} - - -File Selectors -^^^^^^^^^^^^^^ - - -.. class:: DirList() - - The `DirList - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirList.htm>`_ - widget displays a list view of a directory, its previous directories and its - sub-directories. The user can choose one of the directories displayed in the - list or change to another directory. - -.. % Python Demo of: -.. % \ulink{DirList}{http://tix.sourceforge.net/dist/current/demos/samples/DirList.tcl} - - -.. class:: DirTree() - - The `DirTree - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirTree.htm>`_ - widget displays a tree view of a directory, its previous directories and its - sub-directories. The user can choose one of the directories displayed in the - list or change to another directory. - -.. % Python Demo of: -.. % \ulink{DirTree}{http://tix.sourceforge.net/dist/current/demos/samples/DirTree.tcl} - - -.. class:: DirSelectDialog() - - The `DirSelectDialog - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirSelectDialog.…>`_ - widget presents the directories in the file system in a dialog window. The user - can use this dialog window to navigate through the file system to select the - desired directory. - -.. % Python Demo of: -.. % \ulink{DirSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/DirDlg.tcl} - - -.. class:: DirSelectBox() - - The :class:`DirSelectBox` is similar to the standard Motif(TM) directory- - selection box. It is generally used for the user to choose a directory. - DirSelectBox stores the directories mostly recently selected into a ComboBox - widget so that they can be quickly selected again. - - -.. class:: ExFileSelectBox() - - The `ExFileSelectBox - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixExFileSelectBox.…>`_ - widget is usually embedded in a tixExFileSelectDialog widget. It provides an - convenient method for the user to select files. The style of the - :class:`ExFileSelectBox` widget is very similar to the standard file dialog on - MS Windows 3.1. - -.. % Python Demo of: -.. % \ulink{ExFileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/EFileDlg.tcl} - - -.. class:: FileSelectBox() - - The `FileSelectBox - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileSelectBox.htm>`_ - is similar to the standard Motif(TM) file-selection box. It is generally used - for the user to choose a file. FileSelectBox stores the files mostly recently - selected into a :class:`ComboBox` widget so that they can be quickly selected - again. - -.. % Python Demo of: -.. % \ulink{FileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/FileDlg.tcl} - - -.. class:: FileEntry() - - The `FileEntry - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileEntry.htm>`_ - widget can be used to input a filename. The user can type in the filename - manually. Alternatively, the user can press the button widget that sits next to - the entry, which will bring up a file selection dialog. - -.. % Python Demo of: -.. % \ulink{FileEntry}{http://tix.sourceforge.net/dist/current/demos/samples/FileEnt.tcl} - - -Hierachical ListBox -^^^^^^^^^^^^^^^^^^^ - - -.. class:: HList() - - The `HList - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixHList.htm>`_ widget - can be used to display any data that have a hierarchical structure, for example, - file system directory trees. The list entries are indented and connected by - branch lines according to their places in the hierarchy. - -.. % Python Demo of: -.. % \ulink{HList}{http://tix.sourceforge.net/dist/current/demos/samples/HList1.tcl} - - -.. class:: CheckList() - - The `CheckList - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixCheckList.htm>`_ - widget displays a list of items to be selected by the user. CheckList acts - similarly to the Tk checkbutton or radiobutton widgets, except it is capable of - handling many more items than checkbuttons or radiobuttons. - -.. % Python Demo of: -.. % \ulink{ CheckList}{http://tix.sourceforge.net/dist/current/demos/samples/ChkList.tc… -.. % Python Demo of: -.. % \ulink{ScrolledHList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList.tcl} -.. % Python Demo of: -.. % \ulink{ScrolledHList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList2.tcl} - - -.. class:: Tree() - - The `Tree - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTree.htm>`_ widget - can be used to display hierarchical data in a tree form. The user can adjust the - view of the tree by opening or closing parts of the tree. - -.. % Python Demo of: -.. % \ulink{Tree}{http://tix.sourceforge.net/dist/current/demos/samples/Tree.tcl} -.. % Python Demo of: -.. % \ulink{Tree (Dynamic)}{http://tix.sourceforge.net/dist/current/demos/samples/DynTree.tcl} - - -Tabular ListBox -^^^^^^^^^^^^^^^ - - -.. class:: TList() - - The `TList - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTList.htm>`_ widget - can be used to display data in a tabular format. The list entries of a - :class:`TList` widget are similar to the entries in the Tk listbox widget. The - main differences are (1) the :class:`TList` widget can display the list entries - in a two dimensional format and (2) you can use graphical images as well as - multiple colors and fonts for the list entries. - -.. % Python Demo of: -.. % \ulink{ScrolledTList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/STList1.tcl} -.. % Python Demo of: -.. % \ulink{ScrolledTList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/STList2.tcl} -.. % Grid has yet to be added to Python -.. % \subsubsection{Grid Widget} -.. % Python Demo of: -.. % \ulink{Simple Grid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid0.tcl} -.. % Python Demo of: -.. % \ulink{ScrolledGrid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid1.tcl} -.. % Python Demo of: -.. % \ulink{Editable Grid}{http://tix.sourceforge.net/dist/current/demos/samples/EditGrid.tcl} - - -Manager Widgets -^^^^^^^^^^^^^^^ - - -.. class:: PanedWindow() - - The `PanedWindow - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPanedWindow.htm>`_ - widget allows the user to interactively manipulate the sizes of several panes. - The panes can be arranged either vertically or horizontally. The user changes - the sizes of the panes by dragging the resize handle between two panes. - -.. % Python Demo of: -.. % \ulink{PanedWindow}{http://tix.sourceforge.net/dist/current/demos/samples/PanedWin.tcl} - - -.. class:: ListNoteBook() - - The `ListNoteBook - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixListNoteBook.htm>`_ - widget is very similar to the :class:`TixNoteBook` widget: it can be used to - display many windows in a limited space using a notebook metaphor. The notebook - is divided into a stack of pages (windows). At one time only one of these pages - can be shown. The user can navigate through these pages by choosing the name of - the desired page in the :attr:`hlist` subwidget. - -.. % Python Demo of: -.. % \ulink{ListNoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/ListNBK.tcl} - - -.. class:: NoteBook() - - The `NoteBook - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixNoteBook.htm>`_ - widget can be used to display many windows in a limited space using a notebook - metaphor. The notebook is divided into a stack of pages. At one time only one of - these pages can be shown. The user can navigate through these pages by choosing - the visual "tabs" at the top of the NoteBook widget. - -.. % Python Demo of: -.. % \ulink{NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/NoteBook.tcl} - -.. % \subsubsection{Scrolled Widgets} -.. % Python Demo of: -.. % \ulink{ScrolledListBox}{http://tix.sourceforge.net/dist/current/demos/samples/SListBox.tcl} -.. % Python Demo of: -.. % \ulink{ScrolledText}{http://tix.sourceforge.net/dist/current/demos/samples/SText.tcl} -.. % Python Demo of: -.. % \ulink{ScrolledWindow}{http://tix.sourceforge.net/dist/current/demos/samples/SWindow.tcl} -.. % Python Demo of: -.. % \ulink{Canvas Object View}{http://tix.sourceforge.net/dist/current/demos/samples/CObjView.tcl} - - -Image Types -^^^^^^^^^^^ - -The :mod:`Tix` module adds: - -* `pixmap <http://tix.sourceforge.net/dist/current/man/html/TixCmd/pixmap.htm>`_ - capabilities to all :mod:`Tix` and :mod:`Tkinter` widgets to create color images - from XPM files. - - .. % Python Demo of: - .. % \ulink{XPM Image In Button}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm.tcl} - .. % Python Demo of: - .. % \ulink{XPM Image In Menu}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm1.tcl} - -* `Compound - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/compound.htm>`_ image - types can be used to create images that consists of multiple horizontal lines; - each line is composed of a series of items (texts, bitmaps, images or spaces) - arranged from left to right. For example, a compound image can be used to - display a bitmap and a text string simultaneously in a Tk :class:`Button` - widget. - - .. % Python Demo of: - .. % \ulink{Compound Image In Buttons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg.tcl} - .. % Python Demo of: - .. % \ulink{Compound Image In NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg2.tcl} - .. % Python Demo of: - .. % \ulink{Compound Image Notebook Color Tabs}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg4.tcl} - .. % Python Demo of: - .. % \ulink{Compound Image Icons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg3.tcl} - - -Miscellaneous Widgets -^^^^^^^^^^^^^^^^^^^^^ - - -.. class:: InputOnly() - - The `InputOnly - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixInputOnly.htm>`_ - widgets are to accept inputs from the user, which can be done with the ``bind`` - command (Unix only). - - -Form Geometry Manager -^^^^^^^^^^^^^^^^^^^^^ - -In addition, :mod:`Tix` augments :mod:`Tkinter` by providing: - - -.. class:: Form() - - The `Form - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixForm.htm>`_ geometry - manager based on attachment rules for all Tk widgets. - -.. % begin{latexonly} -.. % \subsection{Tix Class Structure} -.. % -.. % \begin{figure}[hbtp] -.. % \centerline{\epsfig{file=hierarchy.png,width=.9\textwidth}} -.. % \vspace{.5cm} -.. % \caption{The Class Hierarchy of Tix Widgets} -.. % \end{figure} -.. % end{latexonly} - - -Tix Commands ------------- - - -.. class:: tixCommand() - - The `tix commands - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tix.htm>`_ provide - access to miscellaneous elements of :mod:`Tix`'s internal state and the - :mod:`Tix` application context. Most of the information manipulated by these - methods pertains to the application as a whole, or to a screen or display, - rather than to a particular window. - - To view the current settings, the common usage is:: - - import Tix - root = Tix.Tk() - print root.tix_configure() - - -.. method:: tixCommand.tix_configure([cnf,] **kw) - - Query or modify the configuration options of the Tix application context. If no - option is specified, returns a dictionary all of the available options. If - option is specified with no value, then the method returns a list describing the - one named option (this list will be identical to the corresponding sublist of - the value returned if no option is specified). If one or more option-value - pairs are specified, then the method modifies the given option(s) to have the - given value(s); in this case the method returns an empty string. Option may be - any of the configuration options. - - -.. method:: tixCommand.tix_cget(option) - - Returns the current value of the configuration option given by *option*. Option - may be any of the configuration options. - - -.. method:: tixCommand.tix_getbitmap(name) - - Locates a bitmap file of the name ``name.xpm`` or ``name`` in one of the bitmap - directories (see the :meth:`tix_addbitmapdir` method). By using - :meth:`tix_getbitmap`, you can avoid hard coding the pathnames of the bitmap - files in your application. When successful, it returns the complete pathname of - the bitmap file, prefixed with the character ``@``. The returned value can be - used to configure the ``bitmap`` option of the Tk and Tix widgets. - - -.. method:: tixCommand.tix_addbitmapdir(directory) - - Tix maintains a list of directories under which the :meth:`tix_getimage` and - :meth:`tix_getbitmap` methods will search for image files. The standard bitmap - directory is :file:`$TIX_LIBRARY/bitmaps`. The :meth:`tix_addbitmapdir` method - adds *directory* into this list. By using this method, the image files of an - applications can also be located using the :meth:`tix_getimage` or - :meth:`tix_getbitmap` method. - - -.. method:: tixCommand.tix_filedialog([dlgclass]) - - Returns the file selection dialog that may be shared among different calls from - this application. This method will create a file selection dialog widget when - it is called the first time. This dialog will be returned by all subsequent - calls to :meth:`tix_filedialog`. An optional dlgclass parameter can be passed - as a string to specified what type of file selection dialog widget is desired. - Possible options are ``tix``, ``FileSelectDialog`` or ``tixExFileSelectDialog``. - - -.. method:: tixCommand.tix_getimage(self, name) - - Locates an image file of the name :file:`name.xpm`, :file:`name.xbm` or - :file:`name.ppm` in one of the bitmap directories (see the - :meth:`tix_addbitmapdir` method above). If more than one file with the same name - (but different extensions) exist, then the image type is chosen according to the - depth of the X display: xbm images are chosen on monochrome displays and color - images are chosen on color displays. By using :meth:`tix_getimage`, you can - avoid hard coding the pathnames of the image files in your application. When - successful, this method returns the name of the newly created image, which can - be used to configure the ``image`` option of the Tk and Tix widgets. - - -.. method:: tixCommand.tix_option_get(name) - - Gets the options maintained by the Tix scheme mechanism. - - -.. method:: tixCommand.tix_resetoptions(newScheme, newFontSet[, newScmPrio]) - - Resets the scheme and fontset of the Tix application to *newScheme* and - *newFontSet*, respectively. This affects only those widgets created after this - call. Therefore, it is best to call the resetoptions method before the creation - of any widgets in a Tix application. - - The optional parameter *newScmPrio* can be given to reset the priority level of - the Tk options set by the Tix schemes. - - Because of the way Tk handles the X option database, after Tix has been has - imported and inited, it is not possible to reset the color schemes and font sets - using the :meth:`tix_config` method. Instead, the :meth:`tix_resetoptions` - method must be used. - - -:mod:`ScrolledText` --- Scrolled Text Widget -============================================ - -.. module:: ScrolledText - :platform: Tk - :synopsis: Text widget with a vertical scroll bar. -.. sectionauthor:: Fred L. Drake, Jr. <fdrake(a)acm.org> - - -The :mod:`ScrolledText` module provides a class of the same name which -implements a basic text widget which has a vertical scroll bar configured to do -the "right thing." Using the :class:`ScrolledText` class is a lot easier than -setting up a text widget and scroll bar directly. The constructor is the same -as that of the :class:`Tkinter.Text` class. - -The text widget and scrollbar are packed together in a :class:`Frame`, and the -methods of the :class:`Grid` and :class:`Pack` geometry managers are acquired -from the :class:`Frame` object. This allows the :class:`ScrolledText` widget to -be used directly to achieve most normal geometry management behavior. - -Should more specific control be necessary, the following attributes are -available: - - -.. attribute:: ScrolledText.frame - - The frame which surrounds the text and scroll bar widgets. - - -.. attribute:: ScrolledText.vbar - - The scroll bar widget. - -XXX: input{libturtle} :XXX - -.. _idle: - -Idle -==== - -.. moduleauthor:: Guido van Rossum <guido(a)Python.org> - - -.. % \declaremodule{standard}{idle} -.. % \modulesynopsis{A Python Integrated Development Environment} - -.. index:: - single: Idle - single: Python Editor - single: Integrated Development Environment - -Idle is the Python IDE built with the :mod:`Tkinter` GUI toolkit. - -IDLE has the following features: - -* coded in 100% pure Python, using the :mod:`Tkinter` GUI toolkit - -* cross-platform: works on Windows and Unix (on Mac OS, there are currently - problems with Tcl/Tk) - -* multi-window text editor with multiple undo, Python colorizing and many other - features, e.g. smart indent and call tips - -* Python shell window (a.k.a. interactive interpreter) - -* debugger (not complete, but you can set breakpoints, view and step) - - -Menus ------ - - -File menu -^^^^^^^^^ - -New window - create a new editing window - -Open... - open an existing file - -Open module... - open an existing module (searches sys.path) - -Class browser - show classes and methods in current file - -Path browser - show sys.path directories, modules, classes and methods - -.. index:: - single: Class browser - single: Path browser - -Save - save current window to the associated file (unsaved windows have a \* before and - after the window title) - -Save As... - save current window to new file, which becomes the associated file - -Save Copy As... - save current window to different file without changing the associated file - -Close - close current window (asks to save if unsaved) - -Exit - close all windows and quit IDLE (asks to save if unsaved) - - -Edit menu -^^^^^^^^^ - -Undo - Undo last change to current window (max 1000 changes) - -Redo - Redo last undone change to current window - -Cut - Copy selection into system-wide clipboard; then delete selection - -Copy - Copy selection into system-wide clipboard - -Paste - Insert system-wide clipboard into window - -Select All - Select the entire contents of the edit buffer - -Find... - Open a search dialog box with many options - -Find again - Repeat last search - -Find selection - Search for the string in the selection - -Find in Files... - Open a search dialog box for searching files - -Replace... - Open a search-and-replace dialog box - -Go to line - Ask for a line number and show that line - -Indent region - Shift selected lines right 4 spaces - -Dedent region - Shift selected lines left 4 spaces - -Comment out region - Insert ## in front of selected lines - -Uncomment region - Remove leading # or ## from selected lines - -Tabify region - Turns *leading* stretches of spaces into tabs - -Untabify region - Turn *all* tabs into the right number of spaces - -Expand word - Expand the word you have typed to match another word in the same buffer; repeat - to get a different expansion - -Format Paragraph - Reformat the current blank-line-separated paragraph - -Import module - Import or reload the current module - -Run script - Execute the current file in the __main__ namespace - -.. index:: - single: Import module - single: Run script - - -Windows menu -^^^^^^^^^^^^ - -Zoom Height - toggles the window between normal size (24x80) and maximum height. - -The rest of this menu lists the names of all open windows; select one to bring -it to the foreground (deiconifying it if necessary). - - -Debug menu (in the Python Shell window only) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Go to file/line - look around the insert point for a filename and linenumber, open the file, and - show the line. - -Open stack viewer - show the stack traceback of the last exception - -Debugger toggle - Run commands in the shell under the debugger - -JIT Stack viewer toggle - Open stack viewer on traceback - -.. index:: - single: stack viewer - single: debugger - - -Basic editing and navigation ----------------------------- - -* :kbd:`Backspace` deletes to the left; :kbd:`Del` deletes to the right - -* Arrow keys and :kbd:`Page Up`/:kbd:`Page Down` to move around - -* :kbd:`Home`/:kbd:`End` go to begin/end of line - -* :kbd:`C-Home`/:kbd:`C-End` go to begin/end of file - -* Some :program:`Emacs` bindings may also work, including :kbd:`C-B`, - :kbd:`C-P`, :kbd:`C-A`, :kbd:`C-E`, :kbd:`C-D`, :kbd:`C-L` - - -Automatic indentation -^^^^^^^^^^^^^^^^^^^^^ - -After a block-opening statement, the next line is indented by 4 spaces (in the -Python Shell window by one tab). After certain keywords (break, return etc.) -the next line is dedented. In leading indentation, :kbd:`Backspace` deletes up -to 4 spaces if they are there. :kbd:`Tab` inserts 1-4 spaces (in the Python -Shell window one tab). See also the indent/dedent region commands in the edit -menu. - - -Python Shell window -^^^^^^^^^^^^^^^^^^^ - -* :kbd:`C-C` interrupts executing command - -* :kbd:`C-D` sends end-of-file; closes window if typed at a ``>>>`` prompt - -* :kbd:`Alt-p` retrieves previous command matching what you have typed - -* :kbd:`Alt-n` retrieves next - -* :kbd:`Return` while on any previous command retrieves that command - -* :kbd:`Alt-/` (Expand word) is also useful here - -.. index:: single: indentation - - -Syntax colors -------------- - -The coloring is applied in a background "thread," so you may occasionally see -uncolorized text. To change the color scheme, edit the ``[Colors]`` section in -:file:`config.txt`. - -Python syntax colors: - Keywords - orange - - Strings - green - - Comments - red - - Definitions - blue - -Shell colors: - Console output - brown - - stdout - blue - - stderr - dark green - - stdin - black - - -Command line usage -^^^^^^^^^^^^^^^^^^ - -:: - - idle.py [-c command] [-d] [-e] [-s] [-t title] [arg] ... - - -c command run this command - -d enable debugger - -e edit mode; arguments are files to be edited - -s run $IDLESTARTUP or $PYTHONSTARTUP first - -t title set title of shell window - -If there are arguments: - -#. If :option:`-e` is used, arguments are files opened for editing and - ``sys.argv`` reflects the arguments passed to IDLE itself. - -#. Otherwise, if :option:`-c` is used, all arguments are placed in - ``sys.argv[1:...]``, with ``sys.argv[0]`` set to ``'-c'``. - -#. Otherwise, if neither :option:`-e` nor :option:`-c` is used, the first - argument is a script which is executed with the remaining arguments in - ``sys.argv[1:...]`` and ``sys.argv[0]`` set to the script name. If the script - name is '-', no script is executed but an interactive Python session is started; - the arguments are still available in ``sys.argv``. - - -.. _other-gui-packages: - -Other Graphical User Interface Packages -======================================= - -There are an number of extension widget sets to :mod:`Tkinter`. - - -.. seealso:: - - `Python megawidgets <http://pmw.sourceforge.net/>`_ - is a toolkit for building high-level compound widgets in Python using the - :mod:`Tkinter` module. It consists of a set of base classes and a library of - flexible and extensible megawidgets built on this foundation. These megawidgets - include notebooks, comboboxes, selection widgets, paned widgets, scrolled - widgets, dialog windows, etc. Also, with the Pmw.Blt interface to BLT, the - busy, graph, stripchart, tabset and vector commands are be available. - - The initial ideas for Pmw were taken from the Tk ``itcl`` extensions ``[incr - Tk]`` by Michael McLennan and ``[incr Widgets]`` by Mark Ulferts. Several of the - megawidgets are direct translations from the itcl to Python. It offers most of - the range of widgets that ``[incr Widgets]`` does, and is almost as complete as - Tix, lacking however Tix's fast :class:`HList` widget for drawing trees. - - `Tkinter3000 Widget Construction Kit (WCK) <http://tkinter.effbot.org/>`_ - is a library that allows you to write new Tkinter widgets in pure Python. The - WCK framework gives you full control over widget creation, configuration, screen - appearance, and event handling. WCK widgets can be very fast and light-weight, - since they can operate directly on Python data structures, without having to - transfer data through the Tk/Tcl layer. - - .. % - -Other GUI packages are also available for Python: - - -.. seealso:: - - `wxPython <http://www.wxpython.org>`_ - wxPython is a cross-platform GUI toolkit for Python that is built around the - popular `wxWidgets <http://www.wxwidgets.org/>`_ C++ toolkit. It provides a - native look and feel for applications on Windows, Mac OS X, and Unix systems by - using each platform's native widgets where ever possible, (GTK+ on Unix-like - systems). In addition to an extensive set of widgets, wxPython provides classes - for online documentation and context sensitive help, printing, HTML viewing, - low-level device context drawing, drag and drop, system clipboard access, an - XML-based resource format and more, including an ever growing library of user- - contributed modules. Both the wxWidgets and wxPython projects are under active - development and continuous improvement, and have active and helpful user and - developer communities. - - `wxPython in Action <http://www.amazon.com/exec/obidos/ASIN/1932394621>`_ - The wxPython book, by Noel Rappin and Robin Dunn. - - PyQt - PyQt is a :program:`sip`\ -wrapped binding to the Qt toolkit. Qt is an - extensive C++ GUI toolkit that is available for Unix, Windows and Mac OS X. - :program:`sip` is a tool for generating bindings for C++ libraries as Python - classes, and is specifically designed for Python. An online manual is available - at http://www.opendocspublishing.com/pyqt/ (errata are located at - http://www.valdyas.org/python/book.html). - - `PyKDE <http://www.riverbankcomputing.co.uk/pykde/index.php>`_ - PyKDE is a :program:`sip`\ -wrapped interface to the KDE desktop libraries. KDE - is a desktop environment for Unix computers; the graphical components are based - on Qt. - - `FXPy <http://fxpy.sourceforge.net/>`_ - is a Python extension module which provides an interface to the `FOX - <http://www.cfdrc.com/FOX/fox.html>`_ GUI. FOX is a C++ based Toolkit for - developing Graphical User Interfaces easily and effectively. It offers a wide, - and growing, collection of Controls, and provides state of the art facilities - such as drag and drop, selection, as well as OpenGL widgets for 3D graphical - manipulation. FOX also implements icons, images, and user-convenience features - such as status line help, and tooltips. - - Even though FOX offers a large collection of controls already, FOX leverages C++ - to allow programmers to easily build additional Controls and GUI elements, - simply by taking existing controls, and creating a derived class which simply - adds or redefines the desired behavior. - - `PyGTK <http://www.daa.com.au/~james/software/pygtk/>`_ - is a set of bindings for the `GTK <http://www.gtk.org/>`_ widget set. It - provides an object oriented interface that is slightly higher level than the C - one. It automatically does all the type casting and reference counting that you - would have to do normally with the C API. There are also `bindings - <http://www.daa.com.au/~james/gnome/>`_ to `GNOME <http://www.gnome.org>`_, and - a `tutorial - <http://laguna.fmedic.unam.mx/~daniel/pygtutorial/pygtutorial/index.html>`_ is - available. - -.. % XXX Reference URLs that compare the different UI packages - Modified: doctools/trunk/Doc-26/library/xml.dom.minidom.rst ============================================================================== --- doctools/trunk/Doc-26/library/xml.dom.minidom.rst (original) +++ doctools/trunk/Doc-26/library/xml.dom.minidom.rst Thu Aug 2 17:44:40 2007 @@ -108,7 +108,7 @@ The W3C recommendation for the DOM supported by :mod:`xml.dom.minidom`. -.. _dom-objects: +.. _minidom-objects: DOM Objects ----------- Modified: doctools/trunk/Doc-26/reference/compound_stmts.rst ============================================================================== --- doctools/trunk/Doc-26/reference/compound_stmts.rst (original) +++ doctools/trunk/Doc-26/reference/compound_stmts.rst Thu Aug 2 17:44:40 2007 @@ -272,7 +272,7 @@ assigned to three variables in the :mod:`sys` module: ``sys.exc_type`` receives the object identifying the exception; ``sys.exc_value`` receives the exception's parameter; ``sys.exc_traceback`` receives a traceback object (see section -:ref:`traceback`) identifying the point in the program where the exception +:ref:`types`) identifying the point in the program where the exception occurred. These details are also available through the :func:`sys.exc_info` function, which returns a tuple ``(exc_type, exc_value, exc_traceback)``. Use of the corresponding variables is deprecated in favor of this function, since Modified: doctools/trunk/Doc-26/reference/datamodel.rst ============================================================================== --- doctools/trunk/Doc-26/reference/datamodel.rst (original) +++ doctools/trunk/Doc-26/reference/datamodel.rst Thu Aug 2 17:44:40 2007 @@ -988,8 +988,6 @@ can implement a Jump command (aka Set Next Statement) by writing to f_lineno. Traceback objects - .. _traceback: - .. index:: object: traceback pair: stack; trace Modified: doctools/trunk/Doc-26/reference/simple_stmts.rst ============================================================================== --- doctools/trunk/Doc-26/reference/simple_stmts.rst (original) +++ doctools/trunk/Doc-26/reference/simple_stmts.rst Thu Aug 2 17:44:40 2007 @@ -563,7 +563,7 @@ .. index:: object: traceback If a third object is present and not ``None``, it must be a traceback object -(see section :ref:`traceback`), and it is substituted instead of the current +(see section :ref:`types`), and it is substituted instead of the current location as the place where the exception occurred. If the third object is present and not a traceback object or ``None``, a :exc:`TypeError` exception is raised. The three-expression form of :keyword:`raise` is useful to re-raise an Modified: doctools/trunk/Doc-3k/TODO ============================================================================== --- doctools/trunk/Doc-3k/TODO (original) +++ doctools/trunk/Doc-3k/TODO Thu Aug 2 17:44:40 2007 @@ -2,7 +2,6 @@ ====================== * fix all references and links marked with `XXX` -* fix all duplicate labels and undefined label references * split very large files and add toctrees * integrate standalone HOWTOs * find out which files get "comments disabled" metadata Modified: doctools/trunk/Doc-3k/c-api/concrete.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/concrete.rst (original) +++ doctools/trunk/Doc-3k/c-api/concrete.rst Thu Aug 2 17:44:40 2007 @@ -3051,7 +3051,7 @@ .. versionadded:: 2.3 -.. _weakref-objects: +.. _weakrefobjects: Weak Reference Objects ---------------------- @@ -3285,7 +3285,7 @@ *NULL*. -.. _datetime-objects: +.. _datetimeobjects: DateTime Objects ---------------- Modified: doctools/trunk/Doc-3k/c-api/intro.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/intro.rst (original) +++ doctools/trunk/Doc-3k/c-api/intro.rst Thu Aug 2 17:44:40 2007 @@ -1,7 +1,7 @@ .. highlightlang:: c -.. _intro: +.. _api-intro: ************ Introduction @@ -30,7 +30,7 @@ application. -.. _includes: +.. _api-includes: Include Files ============= @@ -80,7 +80,7 @@ is no need to do anything special to use the API from C++. -.. _objects: +.. _api-objects: Objects, Types and Reference Counts =================================== @@ -107,7 +107,7 @@ pointed to by *a* is a Python list. -.. _refcounts: +.. _api-refcounts: Reference Counts ---------------- @@ -170,7 +170,7 @@ they are done with the result; this soon becomes second nature. -.. _refcountdetails: +.. _api-refcountdetails: Reference Count Details ^^^^^^^^^^^^^^^^^^^^^^^ @@ -335,7 +335,7 @@ .. index:: single: sum_sequence() -.. _types: +.. _api-types: Types ----- @@ -349,7 +349,7 @@ use them. -.. _exceptions: +.. _api-exceptions: Exceptions ========== @@ -496,7 +496,7 @@ the final call made is successful. -.. _embedding: +.. _api-embedding: Embedding Python ================ @@ -520,8 +520,6 @@ :mod:`__builtin__`, :mod:`__main__`, :mod:`sys`, and :mod:`exceptions`. It also initializes the module search path (``sys.path``). -.. % - .. index:: single: PySys_SetArgv() :cfunc:`Py_Initialize` does not set the "script argument list" (``sys.argv``). @@ -574,7 +572,7 @@ allocated by extension modules currently cannot be released. -.. _debugging: +.. _api-debugging: Debugging Builds ================ Modified: doctools/trunk/Doc-3k/conf.py ============================================================================== --- doctools/trunk/Doc-3k/conf.py (original) +++ doctools/trunk/Doc-3k/conf.py Thu Aug 2 17:44:40 2007 @@ -34,6 +34,7 @@ 'whatsnew/2.6.rst', 'maclib/scrap.rst', 'library/xmllib.rst', + 'library/xml.etree.rst', ] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, Modified: doctools/trunk/Doc-3k/distutils/apiref.rst ============================================================================== --- doctools/trunk/Doc-3k/distutils/apiref.rst (original) +++ doctools/trunk/Doc-3k/distutils/apiref.rst Thu Aug 2 17:44:40 2007 @@ -1415,7 +1415,118 @@ Also provides :func:`find_executable` to search the path for a given executable name. -XXX: input{sysconfig} :XXX + +:mod:`distutils.sysconfig` --- System configuration information +=============================================================== + +.. module:: distutils.sysconfig + :synopsis: Low-level access to configuration information of the Python interpreter. +.. moduleauthor:: Fred L. Drake, Jr. <fdrake(a)acm.org> +.. moduleauthor:: Greg Ward <gward(a)python.net> +.. sectionauthor:: Fred L. Drake, Jr. <fdrake(a)acm.org> + + +The :mod:`distutils.sysconfig` module provides access to Python's low-level +configuration information. The specific configuration variables available +depend heavily on the platform and configuration. The specific variables depend +on the build process for the specific version of Python being run; the variables +are those found in the :file:`Makefile` and configuration header that are +installed with Python on Unix systems. The configuration header is called +:file:`pyconfig.h` for Python versions starting with 2.2, and :file:`config.h` +for earlier versions of Python. + +Some additional functions are provided which perform some useful manipulations +for other parts of the :mod:`distutils` package. + + +.. data:: PREFIX + + The result of ``os.path.normpath(sys.prefix)``. + + +.. data:: EXEC_PREFIX + + The result of ``os.path.normpath(sys.exec_prefix)``. + + +.. function:: get_config_var(name) + + Return the value of a single variable. This is equivalent to + ``get_config_vars().get(name)``. + + +.. function:: get_config_vars(...) + + Return a set of variable definitions. If there are no arguments, this returns a + dictionary mapping names of configuration variables to values. If arguments are + provided, they should be strings, and the return value will be a sequence giving + the associated values. If a given name does not have a corresponding value, + ``None`` will be included for that variable. + + +.. function:: get_config_h_filename() + + Return the full path name of the configuration header. For Unix, this will be + the header generated by the :program:`configure` script; for other platforms the + header will have been supplied directly by the Python source distribution. The + file is a platform-specific text file. + + +.. function:: get_makefile_filename() + + Return the full path name of the :file:`Makefile` used to build Python. For + Unix, this will be a file generated by the :program:`configure` script; the + meaning for other platforms will vary. The file is a platform-specific text + file, if it exists. This function is only useful on POSIX platforms. + + +.. function:: get_python_inc([plat_specific[, prefix]]) + + Return the directory for either the general or platform-dependent C include + files. If *plat_specific* is true, the platform-dependent include directory is + returned; if false or omitted, the platform-independent directory is returned. + If *prefix* is given, it is used as either the prefix instead of + :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if + *plat_specific* is true. + + +.. function:: get_python_lib([plat_specific[, standard_lib[, prefix]]]) + + Return the directory for either the general or platform-dependent library + installation. If *plat_specific* is true, the platform-dependent include + directory is returned; if false or omitted, the platform-independent directory + is returned. If *prefix* is given, it is used as either the prefix instead of + :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if + *plat_specific* is true. If *standard_lib* is true, the directory for the + standard library is returned rather than the directory for the installation of + third-party extensions. + +The following function is only intended for use within the :mod:`distutils` +package. + + +.. function:: customize_compiler(compiler) + + Do any platform-specific customization of a + :class:`distutils.ccompiler.CCompiler` instance. + + This function is only needed on Unix at this time, but should be called + consistently to support forward-compatibility. It inserts the information that + varies across Unix flavors and is stored in Python's :file:`Makefile`. This + information includes the selected compiler, compiler and linker options, and the + extension used by the linker for shared objects. + +This function is even more special-purpose, and should only be used from +Python's own build procedures. + + +.. function:: set_python_build() + + Inform the :mod:`distutils.sysconfig` module that it is being used as part of + the build process for Python. This changes a lot of relative locations for + files, allowing them to be located in the build area rather than in an installed + Python. + :mod:`distutils.text_file` --- The TextFile class ================================================= @@ -1870,20 +1981,3 @@ *sub_commands* is usually defined at the \*end\* of a class, because predicates can be unbound methods, so they must already have been defined. The canonical example is the :command:`install` command. - -.. % -.. % The ugly "%begin{latexonly}" pseudo-environments are really just to -.. % keep LaTeX2HTML quiet during the \renewcommand{} macros; they're -.. % not really valuable. -.. % -.. % begin{latexonly} -.. % end{latexonly} - -XXX: input{moddist.ind} :XXX -.. % Module Index -.. % begin{latexonly} -.. % end{latexonly} - -XXX: input{dist.ind} :XXX -.. % Index - Modified: doctools/trunk/Doc-3k/distutils/introduction.rst ============================================================================== --- doctools/trunk/Doc-3k/distutils/introduction.rst (original) +++ doctools/trunk/Doc-3k/distutils/introduction.rst Thu Aug 2 17:44:40 2007 @@ -1,4 +1,4 @@ -.. _intro: +.. _distutils-intro: **************************** An Introduction to Distutils @@ -10,7 +10,7 @@ Python Modules (XXX reference: ../inst/inst.html) manual. -.. _concepts: +.. _distutils-concepts: Concepts & Terminology ====================== @@ -41,7 +41,7 @@ code. -.. _simple-example: +.. _distutils-simple-example: A Simple Example ================ Modified: doctools/trunk/Doc-3k/distutils/setupscript.rst ============================================================================== --- doctools/trunk/Doc-3k/distutils/setupscript.rst (original) +++ doctools/trunk/Doc-3k/distutils/setupscript.rst Thu Aug 2 17:44:40 2007 @@ -8,7 +8,7 @@ installing modules using the Distutils. The main purpose of the setup script is to describe your module distribution to the Distutils, so that the various commands that operate on your modules do the right thing. As we saw in section -:ref:`simple-example` above, the setup script consists mainly of a call to +:ref:`distutils-simple-example` above, the setup script consists mainly of a call to :func:`setup`, and most information supplied to the Distutils by the module developer is supplied as keyword arguments to :func:`setup`. @@ -33,7 +33,7 @@ ) There are only two differences between this and the trivial one-file -distribution presented in section :ref:`simple-example`: more metadata, and the +distribution presented in section :ref:`distutils-simple-example`: more metadata, and the specification of pure Python modules by package, rather than by module. This is important since the Distutils consist of a couple of dozen modules split into (so far) two packages; an explicit list of every module would be tedious to @@ -114,7 +114,7 @@ For a small module distribution, you might prefer to list all modules rather than listing packages---especially the case of a single module that goes in the "root package" (i.e., no package at all). This simplest case was shown in -section :ref:`simple-example`; here is a slightly more involved example:: +section :ref:`distutils-simple-example`; here is a slightly more involved example:: py_modules = ['mod1', 'pkg.mod2'] Modified: doctools/trunk/Doc-3k/distutils/sourcedist.rst ============================================================================== --- doctools/trunk/Doc-3k/distutils/sourcedist.rst (original) +++ doctools/trunk/Doc-3k/distutils/sourcedist.rst Thu Aug 2 17:44:40 2007 @@ -4,7 +4,7 @@ Creating a Source Distribution ****************************** -As shown in section :ref:`simple-example`, you use the :command:`sdist` command +As shown in section :ref:`distutils-simple-example`, you use the :command:`sdist` command to create a source distribution. In the simplest case, :: python setup.py sdist Deleted: /doctools/trunk/Doc-3k/distutils/sysconfig.rst ============================================================================== --- /doctools/trunk/Doc-3k/distutils/sysconfig.rst Thu Aug 2 17:44:40 2007 +++ (empty file) @@ -1,112 +0,0 @@ - -:mod:`distutils.sysconfig` --- System configuration information -=============================================================== - -.. module:: distutils.sysconfig - :synopsis: Low-level access to configuration information of the Python interpreter. -.. moduleauthor:: Fred L. Drake, Jr. <fdrake(a)acm.org> -.. moduleauthor:: Greg Ward <gward(a)python.net> -.. sectionauthor:: Fred L. Drake, Jr. <fdrake(a)acm.org> - - -The :mod:`distutils.sysconfig` module provides access to Python's low-level -configuration information. The specific configuration variables available -depend heavily on the platform and configuration. The specific variables depend -on the build process for the specific version of Python being run; the variables -are those found in the :file:`Makefile` and configuration header that are -installed with Python on Unix systems. The configuration header is called -:file:`pyconfig.h` for Python versions starting with 2.2, and :file:`config.h` -for earlier versions of Python. - -Some additional functions are provided which perform some useful manipulations -for other parts of the :mod:`distutils` package. - - -.. data:: PREFIX - - The result of ``os.path.normpath(sys.prefix)``. - - -.. data:: EXEC_PREFIX - - The result of ``os.path.normpath(sys.exec_prefix)``. - - -.. function:: get_config_var(name) - - Return the value of a single variable. This is equivalent to - ``get_config_vars().get(name)``. - - -.. function:: get_config_vars(...) - - Return a set of variable definitions. If there are no arguments, this returns a - dictionary mapping names of configuration variables to values. If arguments are - provided, they should be strings, and the return value will be a sequence giving - the associated values. If a given name does not have a corresponding value, - ``None`` will be included for that variable. - - -.. function:: get_config_h_filename() - - Return the full path name of the configuration header. For Unix, this will be - the header generated by the :program:`configure` script; for other platforms the - header will have been supplied directly by the Python source distribution. The - file is a platform-specific text file. - - -.. function:: get_makefile_filename() - - Return the full path name of the :file:`Makefile` used to build Python. For - Unix, this will be a file generated by the :program:`configure` script; the - meaning for other platforms will vary. The file is a platform-specific text - file, if it exists. This function is only useful on POSIX platforms. - - -.. function:: get_python_inc([plat_specific[, prefix]]) - - Return the directory for either the general or platform-dependent C include - files. If *plat_specific* is true, the platform-dependent include directory is - returned; if false or omitted, the platform-independent directory is returned. - If *prefix* is given, it is used as either the prefix instead of - :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if - *plat_specific* is true. - - -.. function:: get_python_lib([plat_specific[, standard_lib[, prefix]]]) - - Return the directory for either the general or platform-dependent library - installation. If *plat_specific* is true, the platform-dependent include - directory is returned; if false or omitted, the platform-independent directory - is returned. If *prefix* is given, it is used as either the prefix instead of - :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if - *plat_specific* is true. If *standard_lib* is true, the directory for the - standard library is returned rather than the directory for the installation of - third-party extensions. - -The following function is only intended for use within the :mod:`distutils` -package. - - -.. function:: customize_compiler(compiler) - - Do any platform-specific customization of a - :class:`distutils.ccompiler.CCompiler` instance. - - This function is only needed on Unix at this time, but should be called - consistently to support forward-compatibility. It inserts the information that - varies across Unix flavors and is stored in Python's :file:`Makefile`. This - information includes the selected compiler, compiler and linker options, and the - extension used by the linker for shared objects. - -This function is even more special-purpose, and should only be used from -Python's own build procedures. - - -.. function:: set_python_build() - - Inform the :mod:`distutils.sysconfig` module that it is being used as part of - the build process for Python. This changes a lot of relative locations for - files, allowing them to be located in the build area rather than in an installed - Python. - Modified: doctools/trunk/Doc-3k/extending/extending.rst ============================================================================== --- doctools/trunk/Doc-3k/extending/extending.rst (original) +++ doctools/trunk/Doc-3k/extending/extending.rst Thu Aug 2 17:44:40 2007 @@ -1,7 +1,7 @@ .. highlightlang:: c -.. _intro: +.. _extending-intro: ****************************** Extending Python with C or C++ @@ -21,7 +21,7 @@ your system setup; details are given in later chapters. -.. _simpleexample: +.. _extending-simpleexample: A Simple Example ================ @@ -103,7 +103,7 @@ return *NULL* immediately (as we saw in the example). -.. _errors: +.. _extending-errors: Intermezzo: Errors and Exceptions ================================= @@ -1107,8 +1107,8 @@ this macro before accessing the C API. The exporting module is a modification of the :mod:`spam` module from section -:ref:`simpleexample`. The function :func:`spam.system` does not call the C -library function :cfunc:`system` directly, but a function +:ref:`extending-simpleexample`. The function :func:`spam.system` does not call +the C library function :cfunc:`system` directly, but a function :cfunc:`PySpam_System`, which would of course do something more complicated in reality (such as adding "spam" to every command). This function :cfunc:`PySpam_System` is also exported to other extension modules. Modified: doctools/trunk/Doc-3k/extending/index.rst ============================================================================== --- doctools/trunk/Doc-3k/extending/index.rst (original) +++ doctools/trunk/Doc-3k/extending/index.rst Thu Aug 2 17:44:40 2007 @@ -17,7 +17,7 @@ This document assumes basic knowledge about Python. For an informal introduction to the language, see :ref:`tutorial-index`. :ref:`reference-index` -gives a more formal definition of the language. :ref:`modules-index` documents +gives a more formal definition of the language. :ref:`library-index` documents the existing object types, functions and modules (both built-in and written in Python) that give the language its wide application range. Deleted: /doctools/trunk/Doc-3k/library/asttable.rst ============================================================================== --- /doctools/trunk/Doc-3k/library/asttable.rst Thu Aug 2 17:44:40 2007 +++ (empty file) @@ -1,288 +0,0 @@ -+-----------------------+--------------------+---------------------------------+ -| Node type | Attribute | Value | -+=======================+====================+=================================+ -| :class:`Add` | :attr:`left` | left operand | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | right operand | -+-----------------------+--------------------+---------------------------------+ -| :class:`And` | :attr:`nodes` | list of operands | -+-----------------------+--------------------+---------------------------------+ -| :class:`AssAttr` | | *attribute as target of | -| | | assignment* | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`expr` | expression on the left-hand | -| | | side of the dot | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`attrname` | the attribute name, a string | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`flags` | XXX | -+-----------------------+--------------------+---------------------------------+ -| :class:`AssList` | :attr:`nodes` | list of list elements being | -| | | assigned to | -+-----------------------+--------------------+---------------------------------+ -| :class:`AssName` | :attr:`name` | name being assigned to | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`flags` | XXX | -+-----------------------+--------------------+---------------------------------+ -| :class:`AssTuple` | :attr:`nodes` | list of tuple elements being | -| | | assigned to | -+-----------------------+--------------------+---------------------------------+ -| :class:`Assert` | :attr:`test` | the expression to be tested | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`fail` | the value of the | -| | | :exc:`AssertionError` | -+-----------------------+--------------------+---------------------------------+ -| :class:`Assign` | :attr:`nodes` | a list of assignment targets, | -| | | one per equal sign | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`expr` | the value being assigned | -+-----------------------+--------------------+---------------------------------+ -| :class:`AugAssign` | :attr:`node` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`op` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Bitand` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Bitor` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Bitxor` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Break` | | | -+-----------------------+--------------------+---------------------------------+ -| :class:`CallFunc` | :attr:`node` | expression for the callee | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`args` | a list of arguments | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`star_args` | the extended \*-arg value | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`dstar_args` | the extended \*\*-arg value | -+-----------------------+--------------------+---------------------------------+ -| :class:`Class` | :attr:`name` | the name of the class, a string | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`bases` | a list of base classes | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`doc` | doc string, a string or | -| | | ``None`` | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`code` | the body of the class statement | -+-----------------------+--------------------+---------------------------------+ -| :class:`Compare` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`ops` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Const` | :attr:`value` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Continue` | | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Decorators` | :attr:`nodes` | List of function decorator | -| | | expressions | -+-----------------------+--------------------+---------------------------------+ -| :class:`Dict` | :attr:`items` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Discard` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Div` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Ellipsis` | | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Expression` | :attr:`node` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Exec` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`locals` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`globals` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`FloorDiv` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`For` | :attr:`assign` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`list` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`body` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`else_` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`From` | :attr:`modname` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`names` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Function` | :attr:`decorators` | :class:`Decorators` or ``None`` | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`name` | name used in def, a string | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`argnames` | list of argument names, as | -| | | strings | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`defaults` | list of default values | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`flags` | xxx | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`doc` | doc string, a string or | -| | | ``None`` | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`code` | the body of the function | -+-----------------------+--------------------+---------------------------------+ -| :class:`GenExpr` | :attr:`code` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`GenExprFor` | :attr:`assign` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`iter` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`ifs` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`GenExprIf` | :attr:`test` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`GenExprInner` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`quals` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Getattr` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`attrname` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Global` | :attr:`names` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`If` | :attr:`tests` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`else_` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Import` | :attr:`names` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Invert` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Keyword` | :attr:`name` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Lambda` | :attr:`argnames` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`defaults` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`flags` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`code` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`LeftShift` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`List` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`ListComp` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`quals` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`ListCompFor` | :attr:`assign` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`list` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`ifs` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`ListCompIf` | :attr:`test` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Mod` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Module` | :attr:`doc` | doc string, a string or | -| | | ``None`` | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`node` | body of the module, a | -| | | :class:`Stmt` | -+-----------------------+--------------------+---------------------------------+ -| :class:`Mul` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Name` | :attr:`name` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Not` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Or` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Pass` | | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Power` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Print` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`dest` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Printnl` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`dest` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Raise` | :attr:`expr1` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`expr2` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`expr3` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Return` | :attr:`value` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`RightShift` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Slice` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`flags` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`lower` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`upper` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Sliceobj` | :attr:`nodes` | list of statements | -+-----------------------+--------------------+---------------------------------+ -| :class:`Stmt` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Sub` | :attr:`left` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`right` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Subscript` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`flags` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`subs` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`TryExcept` | :attr:`body` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`handlers` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`else_` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`TryFinally` | :attr:`body` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`final` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Tuple` | :attr:`nodes` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`UnaryAdd` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`UnarySub` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`While` | :attr:`test` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`body` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`else_` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`With` | :attr:`expr` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`vars` | | -+-----------------------+--------------------+---------------------------------+ -| | :attr:`body` | | -+-----------------------+--------------------+---------------------------------+ -| :class:`Yield` | :attr:`value` | | -+-----------------------+--------------------+---------------------------------+ - Modified: doctools/trunk/Doc-3k/library/contextlib.rst ============================================================================== --- doctools/trunk/Doc-3k/library/contextlib.rst (original) +++ doctools/trunk/Doc-3k/library/contextlib.rst Thu Aug 2 17:44:40 2007 @@ -82,8 +82,6 @@ :meth:`__exit__` methods should avoid raising exceptions, and in particular they should not re-raise a passed-in exception. -.. _context-closing: - .. function:: closing(thing) Modified: doctools/trunk/Doc-3k/library/cookielib.rst ============================================================================== --- doctools/trunk/Doc-3k/library/cookielib.rst (original) +++ doctools/trunk/Doc-3k/library/cookielib.rst Thu Aug 2 17:44:40 2007 @@ -32,9 +32,8 @@ :mailheader:`Set-Cookie2` headers (eg. ``domain`` and ``expires``) are conventionally referred to as :dfn:`attributes`. To distinguish them from Python attributes, the documentation for this module uses the term - :dfn:`cookie-attribute` instead + :dfn:`cookie-attribute` instead. -. The module defines the following exception: @@ -47,9 +46,8 @@ .. note:: For backwards-compatibility with Python 2.4 (which raised an :exc:`IOError`), - :exc:`LoadError` is a subclass of :exc:`IOError` + :exc:`LoadError` is a subclass of :exc:`IOError`. - . The following classes are provided: @@ -601,7 +599,7 @@ Equivalent to ``DomainStrictNoDots|DomainStrictNonDomain``. -.. _cookie-objects: +.. _cookielib-cookie-objects: Cookie Objects -------------- Added: doctools/trunk/Doc-3k/library/idle.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-3k/library/idle.rst Thu Aug 2 17:44:40 2007 @@ -0,0 +1,288 @@ +.. _idle: + +Idle +==== + +.. moduleauthor:: Guido van Rossum <guido(a)Python.org> + + +.. % \declaremodule{standard}{idle} +.. % \modulesynopsis{A Python Integrated Development Environment} + +.. index:: + single: Idle + single: Python Editor + single: Integrated Development Environment + +Idle is the Python IDE built with the :mod:`Tkinter` GUI toolkit. + +IDLE has the following features: + +* coded in 100% pure Python, using the :mod:`Tkinter` GUI toolkit + +* cross-platform: works on Windows and Unix (on Mac OS, there are currently + problems with Tcl/Tk) + +* multi-window text editor with multiple undo, Python colorizing and many other + features, e.g. smart indent and call tips + +* Python shell window (a.k.a. interactive interpreter) + +* debugger (not complete, but you can set breakpoints, view and step) + + +Menus +----- + + +File menu +^^^^^^^^^ + +New window + create a new editing window + +Open... + open an existing file + +Open module... + open an existing module (searches sys.path) + +Class browser + show classes and methods in current file + +Path browser + show sys.path directories, modules, classes and methods + +.. index:: + single: Class browser + single: Path browser + +Save + save current window to the associated file (unsaved windows have a \* before and + after the window title) + +Save As... + save current window to new file, which becomes the associated file + +Save Copy As... + save current window to different file without changing the associated file + +Close + close current window (asks to save if unsaved) + +Exit + close all windows and quit IDLE (asks to save if unsaved) + + +Edit menu +^^^^^^^^^ + +Undo + Undo last change to current window (max 1000 changes) + +Redo + Redo last undone change to current window + +Cut + Copy selection into system-wide clipboard; then delete selection + +Copy + Copy selection into system-wide clipboard + +Paste + Insert system-wide clipboard into window + +Select All + Select the entire contents of the edit buffer + +Find... + Open a search dialog box with many options + +Find again + Repeat last search + +Find selection + Search for the string in the selection + +Find in Files... + Open a search dialog box for searching files + +Replace... + Open a search-and-replace dialog box + +Go to line + Ask for a line number and show that line + +Indent region + Shift selected lines right 4 spaces + +Dedent region + Shift selected lines left 4 spaces + +Comment out region + Insert ## in front of selected lines + +Uncomment region + Remove leading # or ## from selected lines + +Tabify region + Turns *leading* stretches of spaces into tabs + +Untabify region + Turn *all* tabs into the right number of spaces + +Expand word + Expand the word you have typed to match another word in the same buffer; repeat + to get a different expansion + +Format Paragraph + Reformat the current blank-line-separated paragraph + +Import module + Import or reload the current module + +Run script + Execute the current file in the __main__ namespace + +.. index:: + single: Import module + single: Run script + + +Windows menu +^^^^^^^^^^^^ + +Zoom Height + toggles the window between normal size (24x80) and maximum height. + +The rest of this menu lists the names of all open windows; select one to bring +it to the foreground (deiconifying it if necessary). + + +Debug menu (in the Python Shell window only) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Go to file/line + look around the insert point for a filename and linenumber, open the file, and + show the line. + +Open stack viewer + show the stack traceback of the last exception + +Debugger toggle + Run commands in the shell under the debugger + +JIT Stack viewer toggle + Open stack viewer on traceback + +.. index:: + single: stack viewer + single: debugger + + +Basic editing and navigation +---------------------------- + +* :kbd:`Backspace` deletes to the left; :kbd:`Del` deletes to the right + +* Arrow keys and :kbd:`Page Up`/:kbd:`Page Down` to move around + +* :kbd:`Home`/:kbd:`End` go to begin/end of line + +* :kbd:`C-Home`/:kbd:`C-End` go to begin/end of file + +* Some :program:`Emacs` bindings may also work, including :kbd:`C-B`, + :kbd:`C-P`, :kbd:`C-A`, :kbd:`C-E`, :kbd:`C-D`, :kbd:`C-L` + + +Automatic indentation +^^^^^^^^^^^^^^^^^^^^^ + +After a block-opening statement, the next line is indented by 4 spaces (in the +Python Shell window by one tab). After certain keywords (break, return etc.) +the next line is dedented. In leading indentation, :kbd:`Backspace` deletes up +to 4 spaces if they are there. :kbd:`Tab` inserts 1-4 spaces (in the Python +Shell window one tab). See also the indent/dedent region commands in the edit +menu. + + +Python Shell window +^^^^^^^^^^^^^^^^^^^ + +* :kbd:`C-C` interrupts executing command + +* :kbd:`C-D` sends end-of-file; closes window if typed at a ``>>>`` prompt + +* :kbd:`Alt-p` retrieves previous command matching what you have typed + +* :kbd:`Alt-n` retrieves next + +* :kbd:`Return` while on any previous command retrieves that command + +* :kbd:`Alt-/` (Expand word) is also useful here + +.. index:: single: indentation + + +Syntax colors +------------- + +The coloring is applied in a background "thread," so you may occasionally see +uncolorized text. To change the color scheme, edit the ``[Colors]`` section in +:file:`config.txt`. + +Python syntax colors: + Keywords + orange + + Strings + green + + Comments + red + + Definitions + blue + +Shell colors: + Console output + brown + + stdout + blue + + stderr + dark green + + stdin + black + + +Command line usage +^^^^^^^^^^^^^^^^^^ + +:: + + idle.py [-c command] [-d] [-e] [-s] [-t title] [arg] ... + + -c command run this command + -d enable debugger + -e edit mode; arguments are files to be edited + -s run $IDLESTARTUP or $PYTHONSTARTUP first + -t title set title of shell window + +If there are arguments: + +#. If :option:`-e` is used, arguments are files opened for editing and + ``sys.argv`` reflects the arguments passed to IDLE itself. + +#. Otherwise, if :option:`-c` is used, all arguments are placed in + ``sys.argv[1:...]``, with ``sys.argv[0]`` set to ``'-c'``. + +#. Otherwise, if neither :option:`-e` nor :option:`-c` is used, the first + argument is a script which is executed with the remaining arguments in + ``sys.argv[1:...]`` and ``sys.argv[0]`` set to the script name. If the script + name is '-', no script is executed but an interactive Python session is started; + the arguments are still available in ``sys.argv``. + + Modified: doctools/trunk/Doc-3k/library/index.rst ============================================================================== --- doctools/trunk/Doc-3k/library/index.rst (original) +++ doctools/trunk/Doc-3k/library/index.rst Thu Aug 2 17:44:40 2007 @@ -51,7 +51,7 @@ ipc.rst internet.rst mm.rst - tkinter.rst + tk.rst i18n.rst frameworks.rst development.rst Modified: doctools/trunk/Doc-3k/library/intro.rst ============================================================================== --- doctools/trunk/Doc-3k/library/intro.rst (original) +++ doctools/trunk/Doc-3k/library/intro.rst Thu Aug 2 17:44:40 2007 @@ -1,5 +1,5 @@ -.. _intro: +.. _library-intro: ************ Introduction Added: doctools/trunk/Doc-3k/library/othergui.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-3k/library/othergui.rst Thu Aug 2 17:44:40 2007 @@ -0,0 +1,93 @@ +.. _other-gui-packages: + +Other Graphical User Interface Packages +======================================= + +There are an number of extension widget sets to :mod:`Tkinter`. + + +.. seealso:: + + `Python megawidgets <http://pmw.sourceforge.net/>`_ + is a toolkit for building high-level compound widgets in Python using the + :mod:`Tkinter` module. It consists of a set of base classes and a library of + flexible and extensible megawidgets built on this foundation. These megawidgets + include notebooks, comboboxes, selection widgets, paned widgets, scrolled + widgets, dialog windows, etc. Also, with the Pmw.Blt interface to BLT, the + busy, graph, stripchart, tabset and vector commands are be available. + + The initial ideas for Pmw were taken from the Tk ``itcl`` extensions ``[incr + Tk]`` by Michael McLennan and ``[incr Widgets]`` by Mark Ulferts. Several of the + megawidgets are direct translations from the itcl to Python. It offers most of + the range of widgets that ``[incr Widgets]`` does, and is almost as complete as + Tix, lacking however Tix's fast :class:`HList` widget for drawing trees. + + `Tkinter3000 Widget Construction Kit (WCK) <http://tkinter.effbot.org/>`_ + is a library that allows you to write new Tkinter widgets in pure Python. The + WCK framework gives you full control over widget creation, configuration, screen + appearance, and event handling. WCK widgets can be very fast and light-weight, + since they can operate directly on Python data structures, without having to + transfer data through the Tk/Tcl layer. + + .. % + +Other GUI packages are also available for Python: + + +.. seealso:: + + `wxPython <http://www.wxpython.org>`_ + wxPython is a cross-platform GUI toolkit for Python that is built around the + popular `wxWidgets <http://www.wxwidgets.org/>`_ C++ toolkit. It provides a + native look and feel for applications on Windows, Mac OS X, and Unix systems by + using each platform's native widgets where ever possible, (GTK+ on Unix-like + systems). In addition to an extensive set of widgets, wxPython provides classes + for online documentation and context sensitive help, printing, HTML viewing, + low-level device context drawing, drag and drop, system clipboard access, an + XML-based resource format and more, including an ever growing library of user- + contributed modules. Both the wxWidgets and wxPython projects are under active + development and continuous improvement, and have active and helpful user and + developer communities. + + `wxPython in Action <http://www.amazon.com/exec/obidos/ASIN/1932394621>`_ + The wxPython book, by Noel Rappin and Robin Dunn. + + PyQt + PyQt is a :program:`sip`\ -wrapped binding to the Qt toolkit. Qt is an + extensive C++ GUI toolkit that is available for Unix, Windows and Mac OS X. + :program:`sip` is a tool for generating bindings for C++ libraries as Python + classes, and is specifically designed for Python. An online manual is available + at http://www.opendocspublishing.com/pyqt/ (errata are located at + http://www.valdyas.org/python/book.html). + + `PyKDE <http://www.riverbankcomputing.co.uk/pykde/index.php>`_ + PyKDE is a :program:`sip`\ -wrapped interface to the KDE desktop libraries. KDE + is a desktop environment for Unix computers; the graphical components are based + on Qt. + + `FXPy <http://fxpy.sourceforge.net/>`_ + is a Python extension module which provides an interface to the `FOX + <http://www.cfdrc.com/FOX/fox.html>`_ GUI. FOX is a C++ based Toolkit for + developing Graphical User Interfaces easily and effectively. It offers a wide, + and growing, collection of Controls, and provides state of the art facilities + such as drag and drop, selection, as well as OpenGL widgets for 3D graphical + manipulation. FOX also implements icons, images, and user-convenience features + such as status line help, and tooltips. + + Even though FOX offers a large collection of controls already, FOX leverages C++ + to allow programmers to easily build additional Controls and GUI elements, + simply by taking existing controls, and creating a derived class which simply + adds or redefines the desired behavior. + + `PyGTK <http://www.daa.com.au/~james/software/pygtk/>`_ + is a set of bindings for the `GTK <http://www.gtk.org/>`_ widget set. It + provides an object oriented interface that is slightly higher level than the C + one. It automatically does all the type casting and reference counting that you + would have to do normally with the C API. There are also `bindings + <http://www.daa.com.au/~james/gnome/>`_ to `GNOME <http://www.gnome.org>`_, and + a `tutorial + <http://laguna.fmedic.unam.mx/~daniel/pygtutorial/pygtutorial/index.html>`_ is + available. + +.. % XXX Reference URLs that compare the different UI packages + Added: doctools/trunk/Doc-3k/library/scrolledtext.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-3k/library/scrolledtext.rst Thu Aug 2 17:44:40 2007 @@ -0,0 +1,32 @@ +:mod:`ScrolledText` --- Scrolled Text Widget +============================================ + +.. module:: ScrolledText + :platform: Tk + :synopsis: Text widget with a vertical scroll bar. +.. sectionauthor:: Fred L. Drake, Jr. <fdrake(a)acm.org> + + +The :mod:`ScrolledText` module provides a class of the same name which +implements a basic text widget which has a vertical scroll bar configured to do +the "right thing." Using the :class:`ScrolledText` class is a lot easier than +setting up a text widget and scroll bar directly. The constructor is the same +as that of the :class:`Tkinter.Text` class. + +The text widget and scrollbar are packed together in a :class:`Frame`, and the +methods of the :class:`Grid` and :class:`Pack` geometry managers are acquired +from the :class:`Frame` object. This allows the :class:`ScrolledText` widget to +be used directly to achieve most normal geometry management behavior. + +Should more specific control be necessary, the following attributes are +available: + + +.. attribute:: ScrolledText.frame + + The frame which surrounds the text and scroll bar widgets. + + +.. attribute:: ScrolledText.vbar + + The scroll bar widget. Modified: doctools/trunk/Doc-3k/library/sqlite3.rst ============================================================================== --- doctools/trunk/Doc-3k/library/sqlite3.rst (original) +++ doctools/trunk/Doc-3k/library/sqlite3.rst Thu Aug 2 17:44:40 2007 @@ -148,9 +148,8 @@ for the lock to go away until raising an exception. The default for the timeout parameter is 5.0 (five seconds). - For the *isolation_level* parameter, please see the :attr:`isolation_level` - property of :class:`Connection` objects in section - :ref:`sqlite3-connection-isolationlevel`. + For the *isolation_level* parameter, please see the + :attr:`Connection.isolation_level` property of :class:`Connection` objects. SQLite natively supports only the types TEXT, INTEGER, FLOAT, BLOB and NULL. If you want to use other types you must add support for them yourself. The @@ -221,9 +220,6 @@ A :class:`Connection` instance has the following attributes and methods: -.. _sqlite3-connection-isolationlevel: - - .. attribute:: Connection.isolation_level Get or set the current isolation level. None for autocommit mode or one of Modified: doctools/trunk/Doc-3k/library/stdtypes.rst ============================================================================== --- doctools/trunk/Doc-3k/library/stdtypes.rst (original) +++ doctools/trunk/Doc-3k/library/stdtypes.rst Thu Aug 2 17:44:40 2007 @@ -1,5 +1,5 @@ -.. _types: +.. _bltin-types: ************** Built-in Types @@ -120,7 +120,7 @@ interpreted as ``not (a == b)``, and ``a == not b`` is a syntax error. -.. _comparisons: +.. _stdcomparisons: Comparisons =========== @@ -1764,9 +1764,8 @@ Not all "file-like" types in Python support use as a context manager for the :keyword:`with` statement. If your code is intended to work with any file-like - object, you can use the :func:`closing` function in the :mod:`contextlib` module - instead of using the object directly. See section :ref:`context-closing` for - details. + object, you can use the function :func:`contextlib.closing` instead of using + the object directly. .. method:: file.flush() Modified: doctools/trunk/Doc-3k/library/strings.rst ============================================================================== --- doctools/trunk/Doc-3k/library/strings.rst (original) +++ doctools/trunk/Doc-3k/library/strings.rst Thu Aug 2 17:44:40 2007 @@ -1,5 +1,5 @@ -.. _strings: +.. _stringservices: *************** String Services Modified: doctools/trunk/Doc-3k/library/tarfile.rst ============================================================================== --- doctools/trunk/Doc-3k/library/tarfile.rst (original) +++ doctools/trunk/Doc-3k/library/tarfile.rst Thu Aug 2 17:44:40 2007 @@ -1,3 +1,4 @@ +.. _tarfile-mod: :mod:`tarfile` --- Read and write tar archive files =================================================== @@ -286,7 +287,7 @@ .. method:: TarFile.open(...) Alternative constructor. The :func:`open` function on module level is actually a - shortcut to this classmethod. See section :ref:`module-tarfile` for details. + shortcut to this classmethod. See section :ref:`tarfile-mod` for details. .. method:: TarFile.getmember(name) Added: doctools/trunk/Doc-3k/library/tix.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-3k/library/tix.rst Thu Aug 2 17:44:40 2007 @@ -0,0 +1,602 @@ +:mod:`Tix` --- Extension widgets for Tk +======================================= + +.. module:: Tix + :synopsis: Tk Extension Widgets for Tkinter +.. sectionauthor:: Mike Clarkson <mikeclarkson(a)users.sourceforge.net> + + +.. index:: single: Tix + +The :mod:`Tix` (Tk Interface Extension) module provides an additional rich set +of widgets. Although the standard Tk library has many useful widgets, they are +far from complete. The :mod:`Tix` library provides most of the commonly needed +widgets that are missing from standard Tk: :class:`HList`, :class:`ComboBox`, +:class:`Control` (a.k.a. SpinBox) and an assortment of scrollable widgets. +:mod:`Tix` also includes many more widgets that are generally useful in a wide +range of applications: :class:`NoteBook`, :class:`FileEntry`, +:class:`PanedWindow`, etc; there are more than 40 of them. + +With all these new widgets, you can introduce new interaction techniques into +applications, creating more useful and more intuitive user interfaces. You can +design your application by choosing the most appropriate widgets to match the +special needs of your application and users. + + +.. seealso:: + + `Tix Homepage <http://tix.sourceforge.net/>`_ + The home page for :mod:`Tix`. This includes links to additional documentation + and downloads. + + `Tix Man Pages <http://tix.sourceforge.net/dist/current/man/>`_ + On-line version of the man pages and reference material. + + `Tix Programming Guide <http://tix.sourceforge.net/dist/current/docs/tix-book/tix.book.html>`_ + On-line version of the programmer's reference material. + + `Tix Development Applications <http://tix.sourceforge.net/Tide/>`_ + Tix applications for development of Tix and Tkinter programs. Tide applications + work under Tk or Tkinter, and include :program:`TixInspect`, an inspector to + remotely modify and debug Tix/Tk/Tkinter applications. + + +Using Tix +--------- + + +.. class:: Tix(screenName[, baseName[, className]]) + + Toplevel widget of Tix which represents mostly the main window of an + application. It has an associated Tcl interpreter. + + Classes in the :mod:`Tix` module subclasses the classes in the :mod:`Tkinter` + module. The former imports the latter, so to use :mod:`Tix` with Tkinter, all + you need to do is to import one module. In general, you can just import + :mod:`Tix`, and replace the toplevel call to :class:`Tkinter.Tk` with + :class:`Tix.Tk`:: + + import Tix + from Tkconstants import * + root = Tix.Tk() + +To use :mod:`Tix`, you must have the :mod:`Tix` widgets installed, usually +alongside your installation of the Tk widgets. To test your installation, try +the following:: + + import Tix + root = Tix.Tk() + root.tk.eval('package require Tix') + +If this fails, you have a Tk installation problem which must be resolved before +proceeding. Use the environment variable :envvar:`TIX_LIBRARY` to point to the +installed :mod:`Tix` library directory, and make sure you have the dynamic +object library (:file:`tix8183.dll` or :file:`libtix8183.so`) in the same +directory that contains your Tk dynamic object library (:file:`tk8183.dll` or +:file:`libtk8183.so`). The directory with the dynamic object library should also +have a file called :file:`pkgIndex.tcl` (case sensitive), which contains the +line:: + + package ifneeded Tix 8.1 [list load "[file join $dir tix8183.dll]" Tix] + +.. % $ <-- bow to font-lock + + +Tix Widgets +----------- + +`Tix <http://tix.sourceforge.net/dist/current/man/html/TixCmd/TixIntro.htm>`_ +introduces over 40 widget classes to the :mod:`Tkinter` repertoire. There is a +demo of all the :mod:`Tix` widgets in the :file:`Demo/tix` directory of the +standard distribution. + +.. % The Python sample code is still being added to Python, hence commented out + + +Basic Widgets +^^^^^^^^^^^^^ + + +.. class:: Balloon() + + A `Balloon + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixBalloon.htm>`_ that + pops up over a widget to provide help. When the user moves the cursor inside a + widget to which a Balloon widget has been bound, a small pop-up window with a + descriptive message will be shown on the screen. + +.. % Python Demo of: +.. % \ulink{Balloon}{http://tix.sourceforge.net/dist/current/demos/samples/Balloon.tcl} + + +.. class:: ButtonBox() + + The `ButtonBox + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixButtonBox.htm>`_ + widget creates a box of buttons, such as is commonly used for ``Ok Cancel``. + +.. % Python Demo of: +.. % \ulink{ButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/BtnBox.tcl} + + +.. class:: ComboBox() + + The `ComboBox + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixComboBox.htm>`_ + widget is similar to the combo box control in MS Windows. The user can select a + choice by either typing in the entry subwdget or selecting from the listbox + subwidget. + +.. % Python Demo of: +.. % \ulink{ComboBox}{http://tix.sourceforge.net/dist/current/demos/samples/ComboBox.tcl} + + +.. class:: Control() + + The `Control + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixControl.htm>`_ + widget is also known as the :class:`SpinBox` widget. The user can adjust the + value by pressing the two arrow buttons or by entering the value directly into + the entry. The new value will be checked against the user-defined upper and + lower limits. + +.. % Python Demo of: +.. % \ulink{Control}{http://tix.sourceforge.net/dist/current/demos/samples/Control.tcl} + + +.. class:: LabelEntry() + + The `LabelEntry + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelEntry.htm>`_ + widget packages an entry widget and a label into one mega widget. It can be used + be used to simplify the creation of "entry-form" type of interface. + +.. % Python Demo of: +.. % \ulink{LabelEntry}{http://tix.sourceforge.net/dist/current/demos/samples/LabEntry.tcl} + + +.. class:: LabelFrame() + + The `LabelFrame + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelFrame.htm>`_ + widget packages a frame widget and a label into one mega widget. To create + widgets inside a LabelFrame widget, one creates the new widgets relative to the + :attr:`frame` subwidget and manage them inside the :attr:`frame` subwidget. + +.. % Python Demo of: +.. % \ulink{LabelFrame}{http://tix.sourceforge.net/dist/current/demos/samples/LabFrame.tcl} + + +.. class:: Meter() + + The `Meter + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixMeter.htm>`_ widget + can be used to show the progress of a background job which may take a long time + to execute. + +.. % Python Demo of: +.. % \ulink{Meter}{http://tix.sourceforge.net/dist/current/demos/samples/Meter.tcl} + + +.. class:: OptionMenu() + + The `OptionMenu + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixOptionMenu.htm>`_ + creates a menu button of options. + +.. % Python Demo of: +.. % \ulink{OptionMenu}{http://tix.sourceforge.net/dist/current/demos/samples/OptMenu.tcl} + + +.. class:: PopupMenu() + + The `PopupMenu + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPopupMenu.htm>`_ + widget can be used as a replacement of the ``tk_popup`` command. The advantage + of the :mod:`Tix` :class:`PopupMenu` widget is it requires less application code + to manipulate. + +.. % Python Demo of: +.. % \ulink{PopupMenu}{http://tix.sourceforge.net/dist/current/demos/samples/PopMenu.tcl} + + +.. class:: Select() + + The `Select + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixSelect.htm>`_ widget + is a container of button subwidgets. It can be used to provide radio-box or + check-box style of selection options for the user. + +.. % Python Demo of: +.. % \ulink{Select}{http://tix.sourceforge.net/dist/current/demos/samples/Select.tcl} + + +.. class:: StdButtonBox() + + The `StdButtonBox + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixStdButtonBox.htm>`_ + widget is a group of standard buttons for Motif-like dialog boxes. + +.. % Python Demo of: +.. % \ulink{StdButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/StdBBox.tcl} + + +File Selectors +^^^^^^^^^^^^^^ + + +.. class:: DirList() + + The `DirList + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirList.htm>`_ + widget displays a list view of a directory, its previous directories and its + sub-directories. The user can choose one of the directories displayed in the + list or change to another directory. + +.. % Python Demo of: +.. % \ulink{DirList}{http://tix.sourceforge.net/dist/current/demos/samples/DirList.tcl} + + +.. class:: DirTree() + + The `DirTree + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirTree.htm>`_ + widget displays a tree view of a directory, its previous directories and its + sub-directories. The user can choose one of the directories displayed in the + list or change to another directory. + +.. % Python Demo of: +.. % \ulink{DirTree}{http://tix.sourceforge.net/dist/current/demos/samples/DirTree.tcl} + + +.. class:: DirSelectDialog() + + The `DirSelectDialog + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirSelectDialog.…>`_ + widget presents the directories in the file system in a dialog window. The user + can use this dialog window to navigate through the file system to select the + desired directory. + +.. % Python Demo of: +.. % \ulink{DirSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/DirDlg.tcl} + + +.. class:: DirSelectBox() + + The :class:`DirSelectBox` is similar to the standard Motif(TM) directory- + selection box. It is generally used for the user to choose a directory. + DirSelectBox stores the directories mostly recently selected into a ComboBox + widget so that they can be quickly selected again. + + +.. class:: ExFileSelectBox() + + The `ExFileSelectBox + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixExFileSelectBox.…>`_ + widget is usually embedded in a tixExFileSelectDialog widget. It provides an + convenient method for the user to select files. The style of the + :class:`ExFileSelectBox` widget is very similar to the standard file dialog on + MS Windows 3.1. + +.. % Python Demo of: +.. % \ulink{ExFileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/EFileDlg.tcl} + + +.. class:: FileSelectBox() + + The `FileSelectBox + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileSelectBox.htm>`_ + is similar to the standard Motif(TM) file-selection box. It is generally used + for the user to choose a file. FileSelectBox stores the files mostly recently + selected into a :class:`ComboBox` widget so that they can be quickly selected + again. + +.. % Python Demo of: +.. % \ulink{FileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/FileDlg.tcl} + + +.. class:: FileEntry() + + The `FileEntry + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileEntry.htm>`_ + widget can be used to input a filename. The user can type in the filename + manually. Alternatively, the user can press the button widget that sits next to + the entry, which will bring up a file selection dialog. + +.. % Python Demo of: +.. % \ulink{FileEntry}{http://tix.sourceforge.net/dist/current/demos/samples/FileEnt.tcl} + + +Hierachical ListBox +^^^^^^^^^^^^^^^^^^^ + + +.. class:: HList() + + The `HList + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixHList.htm>`_ widget + can be used to display any data that have a hierarchical structure, for example, + file system directory trees. The list entries are indented and connected by + branch lines according to their places in the hierarchy. + +.. % Python Demo of: +.. % \ulink{HList}{http://tix.sourceforge.net/dist/current/demos/samples/HList1.tcl} + + +.. class:: CheckList() + + The `CheckList + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixCheckList.htm>`_ + widget displays a list of items to be selected by the user. CheckList acts + similarly to the Tk checkbutton or radiobutton widgets, except it is capable of + handling many more items than checkbuttons or radiobuttons. + +.. % Python Demo of: +.. % \ulink{ CheckList}{http://tix.sourceforge.net/dist/current/demos/samples/ChkList.tc… +.. % Python Demo of: +.. % \ulink{ScrolledHList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList.tcl} +.. % Python Demo of: +.. % \ulink{ScrolledHList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList2.tcl} + + +.. class:: Tree() + + The `Tree + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTree.htm>`_ widget + can be used to display hierarchical data in a tree form. The user can adjust the + view of the tree by opening or closing parts of the tree. + +.. % Python Demo of: +.. % \ulink{Tree}{http://tix.sourceforge.net/dist/current/demos/samples/Tree.tcl} +.. % Python Demo of: +.. % \ulink{Tree (Dynamic)}{http://tix.sourceforge.net/dist/current/demos/samples/DynTree.tcl} + + +Tabular ListBox +^^^^^^^^^^^^^^^ + + +.. class:: TList() + + The `TList + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTList.htm>`_ widget + can be used to display data in a tabular format. The list entries of a + :class:`TList` widget are similar to the entries in the Tk listbox widget. The + main differences are (1) the :class:`TList` widget can display the list entries + in a two dimensional format and (2) you can use graphical images as well as + multiple colors and fonts for the list entries. + +.. % Python Demo of: +.. % \ulink{ScrolledTList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/STList1.tcl} +.. % Python Demo of: +.. % \ulink{ScrolledTList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/STList2.tcl} +.. % Grid has yet to be added to Python +.. % \subsubsection{Grid Widget} +.. % Python Demo of: +.. % \ulink{Simple Grid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid0.tcl} +.. % Python Demo of: +.. % \ulink{ScrolledGrid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid1.tcl} +.. % Python Demo of: +.. % \ulink{Editable Grid}{http://tix.sourceforge.net/dist/current/demos/samples/EditGrid.tcl} + + +Manager Widgets +^^^^^^^^^^^^^^^ + + +.. class:: PanedWindow() + + The `PanedWindow + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPanedWindow.htm>`_ + widget allows the user to interactively manipulate the sizes of several panes. + The panes can be arranged either vertically or horizontally. The user changes + the sizes of the panes by dragging the resize handle between two panes. + +.. % Python Demo of: +.. % \ulink{PanedWindow}{http://tix.sourceforge.net/dist/current/demos/samples/PanedWin.tcl} + + +.. class:: ListNoteBook() + + The `ListNoteBook + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixListNoteBook.htm>`_ + widget is very similar to the :class:`TixNoteBook` widget: it can be used to + display many windows in a limited space using a notebook metaphor. The notebook + is divided into a stack of pages (windows). At one time only one of these pages + can be shown. The user can navigate through these pages by choosing the name of + the desired page in the :attr:`hlist` subwidget. + +.. % Python Demo of: +.. % \ulink{ListNoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/ListNBK.tcl} + + +.. class:: NoteBook() + + The `NoteBook + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixNoteBook.htm>`_ + widget can be used to display many windows in a limited space using a notebook + metaphor. The notebook is divided into a stack of pages. At one time only one of + these pages can be shown. The user can navigate through these pages by choosing + the visual "tabs" at the top of the NoteBook widget. + +.. % Python Demo of: +.. % \ulink{NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/NoteBook.tcl} + +.. % \subsubsection{Scrolled Widgets} +.. % Python Demo of: +.. % \ulink{ScrolledListBox}{http://tix.sourceforge.net/dist/current/demos/samples/SListBox.tcl} +.. % Python Demo of: +.. % \ulink{ScrolledText}{http://tix.sourceforge.net/dist/current/demos/samples/SText.tcl} +.. % Python Demo of: +.. % \ulink{ScrolledWindow}{http://tix.sourceforge.net/dist/current/demos/samples/SWindow.tcl} +.. % Python Demo of: +.. % \ulink{Canvas Object View}{http://tix.sourceforge.net/dist/current/demos/samples/CObjView.tcl} + + +Image Types +^^^^^^^^^^^ + +The :mod:`Tix` module adds: + +* `pixmap <http://tix.sourceforge.net/dist/current/man/html/TixCmd/pixmap.htm>`_ + capabilities to all :mod:`Tix` and :mod:`Tkinter` widgets to create color images + from XPM files. + + .. % Python Demo of: + .. % \ulink{XPM Image In Button}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm.tcl} + .. % Python Demo of: + .. % \ulink{XPM Image In Menu}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm1.tcl} + +* `Compound + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/compound.htm>`_ image + types can be used to create images that consists of multiple horizontal lines; + each line is composed of a series of items (texts, bitmaps, images or spaces) + arranged from left to right. For example, a compound image can be used to + display a bitmap and a text string simultaneously in a Tk :class:`Button` + widget. + + .. % Python Demo of: + .. % \ulink{Compound Image In Buttons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg.tcl} + .. % Python Demo of: + .. % \ulink{Compound Image In NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg2.tcl} + .. % Python Demo of: + .. % \ulink{Compound Image Notebook Color Tabs}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg4.tcl} + .. % Python Demo of: + .. % \ulink{Compound Image Icons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg3.tcl} + + +Miscellaneous Widgets +^^^^^^^^^^^^^^^^^^^^^ + + +.. class:: InputOnly() + + The `InputOnly + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixInputOnly.htm>`_ + widgets are to accept inputs from the user, which can be done with the ``bind`` + command (Unix only). + + +Form Geometry Manager +^^^^^^^^^^^^^^^^^^^^^ + +In addition, :mod:`Tix` augments :mod:`Tkinter` by providing: + + +.. class:: Form() + + The `Form + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixForm.htm>`_ geometry + manager based on attachment rules for all Tk widgets. + +.. % begin{latexonly} +.. % \subsection{Tix Class Structure} +.. % +.. % \begin{figure}[hbtp] +.. % \centerline{\epsfig{file=hierarchy.png,width=.9\textwidth}} +.. % \vspace{.5cm} +.. % \caption{The Class Hierarchy of Tix Widgets} +.. % \end{figure} +.. % end{latexonly} + + +Tix Commands +------------ + + +.. class:: tixCommand() + + The `tix commands + <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tix.htm>`_ provide + access to miscellaneous elements of :mod:`Tix`'s internal state and the + :mod:`Tix` application context. Most of the information manipulated by these + methods pertains to the application as a whole, or to a screen or display, + rather than to a particular window. + + To view the current settings, the common usage is:: + + import Tix + root = Tix.Tk() + print root.tix_configure() + + +.. method:: tixCommand.tix_configure([cnf,] **kw) + + Query or modify the configuration options of the Tix application context. If no + option is specified, returns a dictionary all of the available options. If + option is specified with no value, then the method returns a list describing the + one named option (this list will be identical to the corresponding sublist of + the value returned if no option is specified). If one or more option-value + pairs are specified, then the method modifies the given option(s) to have the + given value(s); in this case the method returns an empty string. Option may be + any of the configuration options. + + +.. method:: tixCommand.tix_cget(option) + + Returns the current value of the configuration option given by *option*. Option + may be any of the configuration options. + + +.. method:: tixCommand.tix_getbitmap(name) + + Locates a bitmap file of the name ``name.xpm`` or ``name`` in one of the bitmap + directories (see the :meth:`tix_addbitmapdir` method). By using + :meth:`tix_getbitmap`, you can avoid hard coding the pathnames of the bitmap + files in your application. When successful, it returns the complete pathname of + the bitmap file, prefixed with the character ``@``. The returned value can be + used to configure the ``bitmap`` option of the Tk and Tix widgets. + + +.. method:: tixCommand.tix_addbitmapdir(directory) + + Tix maintains a list of directories under which the :meth:`tix_getimage` and + :meth:`tix_getbitmap` methods will search for image files. The standard bitmap + directory is :file:`$TIX_LIBRARY/bitmaps`. The :meth:`tix_addbitmapdir` method + adds *directory* into this list. By using this method, the image files of an + applications can also be located using the :meth:`tix_getimage` or + :meth:`tix_getbitmap` method. + + +.. method:: tixCommand.tix_filedialog([dlgclass]) + + Returns the file selection dialog that may be shared among different calls from + this application. This method will create a file selection dialog widget when + it is called the first time. This dialog will be returned by all subsequent + calls to :meth:`tix_filedialog`. An optional dlgclass parameter can be passed + as a string to specified what type of file selection dialog widget is desired. + Possible options are ``tix``, ``FileSelectDialog`` or ``tixExFileSelectDialog``. + + +.. method:: tixCommand.tix_getimage(self, name) + + Locates an image file of the name :file:`name.xpm`, :file:`name.xbm` or + :file:`name.ppm` in one of the bitmap directories (see the + :meth:`tix_addbitmapdir` method above). If more than one file with the same name + (but different extensions) exist, then the image type is chosen according to the + depth of the X display: xbm images are chosen on monochrome displays and color + images are chosen on color displays. By using :meth:`tix_getimage`, you can + avoid hard coding the pathnames of the image files in your application. When + successful, this method returns the name of the newly created image, which can + be used to configure the ``image`` option of the Tk and Tix widgets. + + +.. method:: tixCommand.tix_option_get(name) + + Gets the options maintained by the Tix scheme mechanism. + + +.. method:: tixCommand.tix_resetoptions(newScheme, newFontSet[, newScmPrio]) + + Resets the scheme and fontset of the Tix application to *newScheme* and + *newFontSet*, respectively. This affects only those widgets created after this + call. Therefore, it is best to call the resetoptions method before the creation + of any widgets in a Tix application. + + The optional parameter *newScmPrio* can be given to reset the priority level of + the Tk options set by the Tix schemes. + + Because of the way Tk handles the X option database, after Tix has been has + imported and inited, it is not possible to reset the color schemes and font sets + using the :meth:`tix_config` method. Instead, the :meth:`tix_resetoptions` + method must be used. Added: doctools/trunk/Doc-3k/library/tk.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-3k/library/tk.rst Thu Aug 2 17:44:40 2007 @@ -0,0 +1,40 @@ +.. _tkinter: + +********************************* +Graphical User Interfaces with Tk +********************************* + +.. index:: + single: GUI + single: Graphical User Interface + single: Tkinter + single: Tk + +Tk/Tcl has long been an integral part of Python. It provides a robust and +platform independent windowing toolkit, that is available to Python programmers +using the :mod:`Tkinter` module, and its extension, the :mod:`Tix` module. + +The :mod:`Tkinter` module is a thin object-oriented layer on top of Tcl/Tk. To +use :mod:`Tkinter`, you don't need to write Tcl code, but you will need to +consult the Tk documentation, and occasionally the Tcl documentation. +:mod:`Tkinter` is a set of wrappers that implement the Tk widgets as Python +classes. In addition, the internal module :mod:`_tkinter` provides a threadsafe +mechanism which allows Python and Tcl to interact. + +Tk is not the only GUI for Python; see section :ref:`other-gui-packages` for +more information on other GUI toolkits for Python. + +.. toctree:: + + tkinter.rst + tix.rst + scrolledtext.rst + turtle.rst + idle.rst + othergui.rst + +.. % Other sections I have in mind are +.. % Tkinter internals +.. % Freezing Tkinter applications + + Modified: doctools/trunk/Doc-3k/library/tkinter.rst ============================================================================== --- doctools/trunk/Doc-3k/library/tkinter.rst (original) +++ doctools/trunk/Doc-3k/library/tkinter.rst Thu Aug 2 17:44:40 2007 @@ -1,38 +1,3 @@ - -.. _tkinter: - -********************************* -Graphical User Interfaces with Tk -********************************* - -.. index:: - single: GUI - single: Graphical User Interface - single: Tkinter - single: Tk - -Tk/Tcl has long been an integral part of Python. It provides a robust and -platform independent windowing toolkit, that is available to Python programmers -using the :mod:`Tkinter` module, and its extension, the :mod:`Tix` module. - -The :mod:`Tkinter` module is a thin object-oriented layer on top of Tcl/Tk. To -use :mod:`Tkinter`, you don't need to write Tcl code, but you will need to -consult the Tk documentation, and occasionally the Tcl documentation. -:mod:`Tkinter` is a set of wrappers that implement the Tk widgets as Python -classes. In addition, the internal module :mod:`_tkinter` provides a threadsafe -mechanism which allows Python and Tcl to interact. - -Tk is not the only GUI for Python; see section :ref:`other-gui-packages` for -more information on other GUI toolkits for Python. - -.. % Other sections I have in mind are -.. % Tkinter internals -.. % Freezing Tkinter applications - - -.. toctree:: - - :mod:`Tkinter` --- Python interface to Tcl/Tk ============================================= @@ -873,1024 +838,3 @@ deleted, the image data is deleted as well, and Tk will display an empty box wherever the image was used. - -:mod:`Tix` --- Extension widgets for Tk -======================================= - -.. module:: Tix - :synopsis: Tk Extension Widgets for Tkinter -.. sectionauthor:: Mike Clarkson <mikeclarkson(a)users.sourceforge.net> - - -.. index:: single: Tix - -The :mod:`Tix` (Tk Interface Extension) module provides an additional rich set -of widgets. Although the standard Tk library has many useful widgets, they are -far from complete. The :mod:`Tix` library provides most of the commonly needed -widgets that are missing from standard Tk: :class:`HList`, :class:`ComboBox`, -:class:`Control` (a.k.a. SpinBox) and an assortment of scrollable widgets. -:mod:`Tix` also includes many more widgets that are generally useful in a wide -range of applications: :class:`NoteBook`, :class:`FileEntry`, -:class:`PanedWindow`, etc; there are more than 40 of them. - -With all these new widgets, you can introduce new interaction techniques into -applications, creating more useful and more intuitive user interfaces. You can -design your application by choosing the most appropriate widgets to match the -special needs of your application and users. - - -.. seealso:: - - `Tix Homepage <http://tix.sourceforge.net/>`_ - The home page for :mod:`Tix`. This includes links to additional documentation - and downloads. - - `Tix Man Pages <http://tix.sourceforge.net/dist/current/man/>`_ - On-line version of the man pages and reference material. - - `Tix Programming Guide <http://tix.sourceforge.net/dist/current/docs/tix-book/tix.book.html>`_ - On-line version of the programmer's reference material. - - `Tix Development Applications <http://tix.sourceforge.net/Tide/>`_ - Tix applications for development of Tix and Tkinter programs. Tide applications - work under Tk or Tkinter, and include :program:`TixInspect`, an inspector to - remotely modify and debug Tix/Tk/Tkinter applications. - - -Using Tix ---------- - - -.. class:: Tix(screenName[, baseName[, className]]) - - Toplevel widget of Tix which represents mostly the main window of an - application. It has an associated Tcl interpreter. - - Classes in the :mod:`Tix` module subclasses the classes in the :mod:`Tkinter` - module. The former imports the latter, so to use :mod:`Tix` with Tkinter, all - you need to do is to import one module. In general, you can just import - :mod:`Tix`, and replace the toplevel call to :class:`Tkinter.Tk` with - :class:`Tix.Tk`:: - - import Tix - from Tkconstants import * - root = Tix.Tk() - -To use :mod:`Tix`, you must have the :mod:`Tix` widgets installed, usually -alongside your installation of the Tk widgets. To test your installation, try -the following:: - - import Tix - root = Tix.Tk() - root.tk.eval('package require Tix') - -If this fails, you have a Tk installation problem which must be resolved before -proceeding. Use the environment variable :envvar:`TIX_LIBRARY` to point to the -installed :mod:`Tix` library directory, and make sure you have the dynamic -object library (:file:`tix8183.dll` or :file:`libtix8183.so`) in the same -directory that contains your Tk dynamic object library (:file:`tk8183.dll` or -:file:`libtk8183.so`). The directory with the dynamic object library should also -have a file called :file:`pkgIndex.tcl` (case sensitive), which contains the -line:: - - package ifneeded Tix 8.1 [list load "[file join $dir tix8183.dll]" Tix] - -.. % $ <-- bow to font-lock - - -Tix Widgets ------------ - -`Tix <http://tix.sourceforge.net/dist/current/man/html/TixCmd/TixIntro.htm>`_ -introduces over 40 widget classes to the :mod:`Tkinter` repertoire. There is a -demo of all the :mod:`Tix` widgets in the :file:`Demo/tix` directory of the -standard distribution. - -.. % The Python sample code is still being added to Python, hence commented out - - -Basic Widgets -^^^^^^^^^^^^^ - - -.. class:: Balloon() - - A `Balloon - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixBalloon.htm>`_ that - pops up over a widget to provide help. When the user moves the cursor inside a - widget to which a Balloon widget has been bound, a small pop-up window with a - descriptive message will be shown on the screen. - -.. % Python Demo of: -.. % \ulink{Balloon}{http://tix.sourceforge.net/dist/current/demos/samples/Balloon.tcl} - - -.. class:: ButtonBox() - - The `ButtonBox - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixButtonBox.htm>`_ - widget creates a box of buttons, such as is commonly used for ``Ok Cancel``. - -.. % Python Demo of: -.. % \ulink{ButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/BtnBox.tcl} - - -.. class:: ComboBox() - - The `ComboBox - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixComboBox.htm>`_ - widget is similar to the combo box control in MS Windows. The user can select a - choice by either typing in the entry subwdget or selecting from the listbox - subwidget. - -.. % Python Demo of: -.. % \ulink{ComboBox}{http://tix.sourceforge.net/dist/current/demos/samples/ComboBox.tcl} - - -.. class:: Control() - - The `Control - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixControl.htm>`_ - widget is also known as the :class:`SpinBox` widget. The user can adjust the - value by pressing the two arrow buttons or by entering the value directly into - the entry. The new value will be checked against the user-defined upper and - lower limits. - -.. % Python Demo of: -.. % \ulink{Control}{http://tix.sourceforge.net/dist/current/demos/samples/Control.tcl} - - -.. class:: LabelEntry() - - The `LabelEntry - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelEntry.htm>`_ - widget packages an entry widget and a label into one mega widget. It can be used - be used to simplify the creation of "entry-form" type of interface. - -.. % Python Demo of: -.. % \ulink{LabelEntry}{http://tix.sourceforge.net/dist/current/demos/samples/LabEntry.tcl} - - -.. class:: LabelFrame() - - The `LabelFrame - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelFrame.htm>`_ - widget packages a frame widget and a label into one mega widget. To create - widgets inside a LabelFrame widget, one creates the new widgets relative to the - :attr:`frame` subwidget and manage them inside the :attr:`frame` subwidget. - -.. % Python Demo of: -.. % \ulink{LabelFrame}{http://tix.sourceforge.net/dist/current/demos/samples/LabFrame.tcl} - - -.. class:: Meter() - - The `Meter - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixMeter.htm>`_ widget - can be used to show the progress of a background job which may take a long time - to execute. - -.. % Python Demo of: -.. % \ulink{Meter}{http://tix.sourceforge.net/dist/current/demos/samples/Meter.tcl} - - -.. class:: OptionMenu() - - The `OptionMenu - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixOptionMenu.htm>`_ - creates a menu button of options. - -.. % Python Demo of: -.. % \ulink{OptionMenu}{http://tix.sourceforge.net/dist/current/demos/samples/OptMenu.tcl} - - -.. class:: PopupMenu() - - The `PopupMenu - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPopupMenu.htm>`_ - widget can be used as a replacement of the ``tk_popup`` command. The advantage - of the :mod:`Tix` :class:`PopupMenu` widget is it requires less application code - to manipulate. - -.. % Python Demo of: -.. % \ulink{PopupMenu}{http://tix.sourceforge.net/dist/current/demos/samples/PopMenu.tcl} - - -.. class:: Select() - - The `Select - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixSelect.htm>`_ widget - is a container of button subwidgets. It can be used to provide radio-box or - check-box style of selection options for the user. - -.. % Python Demo of: -.. % \ulink{Select}{http://tix.sourceforge.net/dist/current/demos/samples/Select.tcl} - - -.. class:: StdButtonBox() - - The `StdButtonBox - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixStdButtonBox.htm>`_ - widget is a group of standard buttons for Motif-like dialog boxes. - -.. % Python Demo of: -.. % \ulink{StdButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/StdBBox.tcl} - - -File Selectors -^^^^^^^^^^^^^^ - - -.. class:: DirList() - - The `DirList - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirList.htm>`_ - widget displays a list view of a directory, its previous directories and its - sub-directories. The user can choose one of the directories displayed in the - list or change to another directory. - -.. % Python Demo of: -.. % \ulink{DirList}{http://tix.sourceforge.net/dist/current/demos/samples/DirList.tcl} - - -.. class:: DirTree() - - The `DirTree - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirTree.htm>`_ - widget displays a tree view of a directory, its previous directories and its - sub-directories. The user can choose one of the directories displayed in the - list or change to another directory. - -.. % Python Demo of: -.. % \ulink{DirTree}{http://tix.sourceforge.net/dist/current/demos/samples/DirTree.tcl} - - -.. class:: DirSelectDialog() - - The `DirSelectDialog - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirSelectDialog.…>`_ - widget presents the directories in the file system in a dialog window. The user - can use this dialog window to navigate through the file system to select the - desired directory. - -.. % Python Demo of: -.. % \ulink{DirSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/DirDlg.tcl} - - -.. class:: DirSelectBox() - - The :class:`DirSelectBox` is similar to the standard Motif(TM) directory- - selection box. It is generally used for the user to choose a directory. - DirSelectBox stores the directories mostly recently selected into a ComboBox - widget so that they can be quickly selected again. - - -.. class:: ExFileSelectBox() - - The `ExFileSelectBox - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixExFileSelectBox.…>`_ - widget is usually embedded in a tixExFileSelectDialog widget. It provides an - convenient method for the user to select files. The style of the - :class:`ExFileSelectBox` widget is very similar to the standard file dialog on - MS Windows 3.1. - -.. % Python Demo of: -.. % \ulink{ExFileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/EFileDlg.tcl} - - -.. class:: FileSelectBox() - - The `FileSelectBox - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileSelectBox.htm>`_ - is similar to the standard Motif(TM) file-selection box. It is generally used - for the user to choose a file. FileSelectBox stores the files mostly recently - selected into a :class:`ComboBox` widget so that they can be quickly selected - again. - -.. % Python Demo of: -.. % \ulink{FileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/FileDlg.tcl} - - -.. class:: FileEntry() - - The `FileEntry - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileEntry.htm>`_ - widget can be used to input a filename. The user can type in the filename - manually. Alternatively, the user can press the button widget that sits next to - the entry, which will bring up a file selection dialog. - -.. % Python Demo of: -.. % \ulink{FileEntry}{http://tix.sourceforge.net/dist/current/demos/samples/FileEnt.tcl} - - -Hierachical ListBox -^^^^^^^^^^^^^^^^^^^ - - -.. class:: HList() - - The `HList - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixHList.htm>`_ widget - can be used to display any data that have a hierarchical structure, for example, - file system directory trees. The list entries are indented and connected by - branch lines according to their places in the hierarchy. - -.. % Python Demo of: -.. % \ulink{HList}{http://tix.sourceforge.net/dist/current/demos/samples/HList1.tcl} - - -.. class:: CheckList() - - The `CheckList - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixCheckList.htm>`_ - widget displays a list of items to be selected by the user. CheckList acts - similarly to the Tk checkbutton or radiobutton widgets, except it is capable of - handling many more items than checkbuttons or radiobuttons. - -.. % Python Demo of: -.. % \ulink{ CheckList}{http://tix.sourceforge.net/dist/current/demos/samples/ChkList.tc… -.. % Python Demo of: -.. % \ulink{ScrolledHList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList.tcl} -.. % Python Demo of: -.. % \ulink{ScrolledHList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList2.tcl} - - -.. class:: Tree() - - The `Tree - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTree.htm>`_ widget - can be used to display hierarchical data in a tree form. The user can adjust the - view of the tree by opening or closing parts of the tree. - -.. % Python Demo of: -.. % \ulink{Tree}{http://tix.sourceforge.net/dist/current/demos/samples/Tree.tcl} -.. % Python Demo of: -.. % \ulink{Tree (Dynamic)}{http://tix.sourceforge.net/dist/current/demos/samples/DynTree.tcl} - - -Tabular ListBox -^^^^^^^^^^^^^^^ - - -.. class:: TList() - - The `TList - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTList.htm>`_ widget - can be used to display data in a tabular format. The list entries of a - :class:`TList` widget are similar to the entries in the Tk listbox widget. The - main differences are (1) the :class:`TList` widget can display the list entries - in a two dimensional format and (2) you can use graphical images as well as - multiple colors and fonts for the list entries. - -.. % Python Demo of: -.. % \ulink{ScrolledTList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/STList1.tcl} -.. % Python Demo of: -.. % \ulink{ScrolledTList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/STList2.tcl} -.. % Grid has yet to be added to Python -.. % \subsubsection{Grid Widget} -.. % Python Demo of: -.. % \ulink{Simple Grid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid0.tcl} -.. % Python Demo of: -.. % \ulink{ScrolledGrid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid1.tcl} -.. % Python Demo of: -.. % \ulink{Editable Grid}{http://tix.sourceforge.net/dist/current/demos/samples/EditGrid.tcl} - - -Manager Widgets -^^^^^^^^^^^^^^^ - - -.. class:: PanedWindow() - - The `PanedWindow - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPanedWindow.htm>`_ - widget allows the user to interactively manipulate the sizes of several panes. - The panes can be arranged either vertically or horizontally. The user changes - the sizes of the panes by dragging the resize handle between two panes. - -.. % Python Demo of: -.. % \ulink{PanedWindow}{http://tix.sourceforge.net/dist/current/demos/samples/PanedWin.tcl} - - -.. class:: ListNoteBook() - - The `ListNoteBook - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixListNoteBook.htm>`_ - widget is very similar to the :class:`TixNoteBook` widget: it can be used to - display many windows in a limited space using a notebook metaphor. The notebook - is divided into a stack of pages (windows). At one time only one of these pages - can be shown. The user can navigate through these pages by choosing the name of - the desired page in the :attr:`hlist` subwidget. - -.. % Python Demo of: -.. % \ulink{ListNoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/ListNBK.tcl} - - -.. class:: NoteBook() - - The `NoteBook - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixNoteBook.htm>`_ - widget can be used to display many windows in a limited space using a notebook - metaphor. The notebook is divided into a stack of pages. At one time only one of - these pages can be shown. The user can navigate through these pages by choosing - the visual "tabs" at the top of the NoteBook widget. - -.. % Python Demo of: -.. % \ulink{NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/NoteBook.tcl} - -.. % \subsubsection{Scrolled Widgets} -.. % Python Demo of: -.. % \ulink{ScrolledListBox}{http://tix.sourceforge.net/dist/current/demos/samples/SListBox.tcl} -.. % Python Demo of: -.. % \ulink{ScrolledText}{http://tix.sourceforge.net/dist/current/demos/samples/SText.tcl} -.. % Python Demo of: -.. % \ulink{ScrolledWindow}{http://tix.sourceforge.net/dist/current/demos/samples/SWindow.tcl} -.. % Python Demo of: -.. % \ulink{Canvas Object View}{http://tix.sourceforge.net/dist/current/demos/samples/CObjView.tcl} - - -Image Types -^^^^^^^^^^^ - -The :mod:`Tix` module adds: - -* `pixmap <http://tix.sourceforge.net/dist/current/man/html/TixCmd/pixmap.htm>`_ - capabilities to all :mod:`Tix` and :mod:`Tkinter` widgets to create color images - from XPM files. - - .. % Python Demo of: - .. % \ulink{XPM Image In Button}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm.tcl} - .. % Python Demo of: - .. % \ulink{XPM Image In Menu}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm1.tcl} - -* `Compound - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/compound.htm>`_ image - types can be used to create images that consists of multiple horizontal lines; - each line is composed of a series of items (texts, bitmaps, images or spaces) - arranged from left to right. For example, a compound image can be used to - display a bitmap and a text string simultaneously in a Tk :class:`Button` - widget. - - .. % Python Demo of: - .. % \ulink{Compound Image In Buttons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg.tcl} - .. % Python Demo of: - .. % \ulink{Compound Image In NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg2.tcl} - .. % Python Demo of: - .. % \ulink{Compound Image Notebook Color Tabs}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg4.tcl} - .. % Python Demo of: - .. % \ulink{Compound Image Icons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg3.tcl} - - -Miscellaneous Widgets -^^^^^^^^^^^^^^^^^^^^^ - - -.. class:: InputOnly() - - The `InputOnly - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixInputOnly.htm>`_ - widgets are to accept inputs from the user, which can be done with the ``bind`` - command (Unix only). - - -Form Geometry Manager -^^^^^^^^^^^^^^^^^^^^^ - -In addition, :mod:`Tix` augments :mod:`Tkinter` by providing: - - -.. class:: Form() - - The `Form - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixForm.htm>`_ geometry - manager based on attachment rules for all Tk widgets. - -.. % begin{latexonly} -.. % \subsection{Tix Class Structure} -.. % -.. % \begin{figure}[hbtp] -.. % \centerline{\epsfig{file=hierarchy.png,width=.9\textwidth}} -.. % \vspace{.5cm} -.. % \caption{The Class Hierarchy of Tix Widgets} -.. % \end{figure} -.. % end{latexonly} - - -Tix Commands ------------- - - -.. class:: tixCommand() - - The `tix commands - <http://tix.sourceforge.net/dist/current/man/html/TixCmd/tix.htm>`_ provide - access to miscellaneous elements of :mod:`Tix`'s internal state and the - :mod:`Tix` application context. Most of the information manipulated by these - methods pertains to the application as a whole, or to a screen or display, - rather than to a particular window. - - To view the current settings, the common usage is:: - - import Tix - root = Tix.Tk() - print root.tix_configure() - - -.. method:: tixCommand.tix_configure([cnf,] **kw) - - Query or modify the configuration options of the Tix application context. If no - option is specified, returns a dictionary all of the available options. If - option is specified with no value, then the method returns a list describing the - one named option (this list will be identical to the corresponding sublist of - the value returned if no option is specified). If one or more option-value - pairs are specified, then the method modifies the given option(s) to have the - given value(s); in this case the method returns an empty string. Option may be - any of the configuration options. - - -.. method:: tixCommand.tix_cget(option) - - Returns the current value of the configuration option given by *option*. Option - may be any of the configuration options. - - -.. method:: tixCommand.tix_getbitmap(name) - - Locates a bitmap file of the name ``name.xpm`` or ``name`` in one of the bitmap - directories (see the :meth:`tix_addbitmapdir` method). By using - :meth:`tix_getbitmap`, you can avoid hard coding the pathnames of the bitmap - files in your application. When successful, it returns the complete pathname of - the bitmap file, prefixed with the character ``@``. The returned value can be - used to configure the ``bitmap`` option of the Tk and Tix widgets. - - -.. method:: tixCommand.tix_addbitmapdir(directory) - - Tix maintains a list of directories under which the :meth:`tix_getimage` and - :meth:`tix_getbitmap` methods will search for image files. The standard bitmap - directory is :file:`$TIX_LIBRARY/bitmaps`. The :meth:`tix_addbitmapdir` method - adds *directory* into this list. By using this method, the image files of an - applications can also be located using the :meth:`tix_getimage` or - :meth:`tix_getbitmap` method. - - -.. method:: tixCommand.tix_filedialog([dlgclass]) - - Returns the file selection dialog that may be shared among different calls from - this application. This method will create a file selection dialog widget when - it is called the first time. This dialog will be returned by all subsequent - calls to :meth:`tix_filedialog`. An optional dlgclass parameter can be passed - as a string to specified what type of file selection dialog widget is desired. - Possible options are ``tix``, ``FileSelectDialog`` or ``tixExFileSelectDialog``. - - -.. method:: tixCommand.tix_getimage(self, name) - - Locates an image file of the name :file:`name.xpm`, :file:`name.xbm` or - :file:`name.ppm` in one of the bitmap directories (see the - :meth:`tix_addbitmapdir` method above). If more than one file with the same name - (but different extensions) exist, then the image type is chosen according to the - depth of the X display: xbm images are chosen on monochrome displays and color - images are chosen on color displays. By using :meth:`tix_getimage`, you can - avoid hard coding the pathnames of the image files in your application. When - successful, this method returns the name of the newly created image, which can - be used to configure the ``image`` option of the Tk and Tix widgets. - - -.. method:: tixCommand.tix_option_get(name) - - Gets the options maintained by the Tix scheme mechanism. - - -.. method:: tixCommand.tix_resetoptions(newScheme, newFontSet[, newScmPrio]) - - Resets the scheme and fontset of the Tix application to *newScheme* and - *newFontSet*, respectively. This affects only those widgets created after this - call. Therefore, it is best to call the resetoptions method before the creation - of any widgets in a Tix application. - - The optional parameter *newScmPrio* can be given to reset the priority level of - the Tk options set by the Tix schemes. - - Because of the way Tk handles the X option database, after Tix has been has - imported and inited, it is not possible to reset the color schemes and font sets - using the :meth:`tix_config` method. Instead, the :meth:`tix_resetoptions` - method must be used. - - -:mod:`ScrolledText` --- Scrolled Text Widget -============================================ - -.. module:: ScrolledText - :platform: Tk - :synopsis: Text widget with a vertical scroll bar. -.. sectionauthor:: Fred L. Drake, Jr. <fdrake(a)acm.org> - - -The :mod:`ScrolledText` module provides a class of the same name which -implements a basic text widget which has a vertical scroll bar configured to do -the "right thing." Using the :class:`ScrolledText` class is a lot easier than -setting up a text widget and scroll bar directly. The constructor is the same -as that of the :class:`Tkinter.Text` class. - -The text widget and scrollbar are packed together in a :class:`Frame`, and the -methods of the :class:`Grid` and :class:`Pack` geometry managers are acquired -from the :class:`Frame` object. This allows the :class:`ScrolledText` widget to -be used directly to achieve most normal geometry management behavior. - -Should more specific control be necessary, the following attributes are -available: - - -.. attribute:: ScrolledText.frame - - The frame which surrounds the text and scroll bar widgets. - - -.. attribute:: ScrolledText.vbar - - The scroll bar widget. - -XXX: input{libturtle} :XXX - -.. _idle: - -Idle -==== - -.. moduleauthor:: Guido van Rossum <guido(a)Python.org> - - -.. % \declaremodule{standard}{idle} -.. % \modulesynopsis{A Python Integrated Development Environment} - -.. index:: - single: Idle - single: Python Editor - single: Integrated Development Environment - -Idle is the Python IDE built with the :mod:`Tkinter` GUI toolkit. - -IDLE has the following features: - -* coded in 100% pure Python, using the :mod:`Tkinter` GUI toolkit - -* cross-platform: works on Windows and Unix (on Mac OS, there are currently - problems with Tcl/Tk) - -* multi-window text editor with multiple undo, Python colorizing and many other - features, e.g. smart indent and call tips - -* Python shell window (a.k.a. interactive interpreter) - -* debugger (not complete, but you can set breakpoints, view and step) - - -Menus ------ - - -File menu -^^^^^^^^^ - -New window - create a new editing window - -Open... - open an existing file - -Open module... - open an existing module (searches sys.path) - -Class browser - show classes and methods in current file - -Path browser - show sys.path directories, modules, classes and methods - -.. index:: - single: Class browser - single: Path browser - -Save - save current window to the associated file (unsaved windows have a \* before and - after the window title) - -Save As... - save current window to new file, which becomes the associated file - -Save Copy As... - save current window to different file without changing the associated file - -Close - close current window (asks to save if unsaved) - -Exit - close all windows and quit IDLE (asks to save if unsaved) - - -Edit menu -^^^^^^^^^ - -Undo - Undo last change to current window (max 1000 changes) - -Redo - Redo last undone change to current window - -Cut - Copy selection into system-wide clipboard; then delete selection - -Copy - Copy selection into system-wide clipboard - -Paste - Insert system-wide clipboard into window - -Select All - Select the entire contents of the edit buffer - -Find... - Open a search dialog box with many options - -Find again - Repeat last search - -Find selection - Search for the string in the selection - -Find in Files... - Open a search dialog box for searching files - -Replace... - Open a search-and-replace dialog box - -Go to line - Ask for a line number and show that line - -Indent region - Shift selected lines right 4 spaces - -Dedent region - Shift selected lines left 4 spaces - -Comment out region - Insert ## in front of selected lines - -Uncomment region - Remove leading # or ## from selected lines - -Tabify region - Turns *leading* stretches of spaces into tabs - -Untabify region - Turn *all* tabs into the right number of spaces - -Expand word - Expand the word you have typed to match another word in the same buffer; repeat - to get a different expansion - -Format Paragraph - Reformat the current blank-line-separated paragraph - -Import module - Import or reload the current module - -Run script - Execute the current file in the __main__ namespace - -.. index:: - single: Import module - single: Run script - - -Windows menu -^^^^^^^^^^^^ - -Zoom Height - toggles the window between normal size (24x80) and maximum height. - -The rest of this menu lists the names of all open windows; select one to bring -it to the foreground (deiconifying it if necessary). - - -Debug menu (in the Python Shell window only) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Go to file/line - look around the insert point for a filename and linenumber, open the file, and - show the line. - -Open stack viewer - show the stack traceback of the last exception - -Debugger toggle - Run commands in the shell under the debugger - -JIT Stack viewer toggle - Open stack viewer on traceback - -.. index:: - single: stack viewer - single: debugger - - -Basic editing and navigation ----------------------------- - -* :kbd:`Backspace` deletes to the left; :kbd:`Del` deletes to the right - -* Arrow keys and :kbd:`Page Up`/:kbd:`Page Down` to move around - -* :kbd:`Home`/:kbd:`End` go to begin/end of line - -* :kbd:`C-Home`/:kbd:`C-End` go to begin/end of file - -* Some :program:`Emacs` bindings may also work, including :kbd:`C-B`, - :kbd:`C-P`, :kbd:`C-A`, :kbd:`C-E`, :kbd:`C-D`, :kbd:`C-L` - - -Automatic indentation -^^^^^^^^^^^^^^^^^^^^^ - -After a block-opening statement, the next line is indented by 4 spaces (in the -Python Shell window by one tab). After certain keywords (break, return etc.) -the next line is dedented. In leading indentation, :kbd:`Backspace` deletes up -to 4 spaces if they are there. :kbd:`Tab` inserts 1-4 spaces (in the Python -Shell window one tab). See also the indent/dedent region commands in the edit -menu. - - -Python Shell window -^^^^^^^^^^^^^^^^^^^ - -* :kbd:`C-C` interrupts executing command - -* :kbd:`C-D` sends end-of-file; closes window if typed at a ``>>>`` prompt - -* :kbd:`Alt-p` retrieves previous command matching what you have typed - -* :kbd:`Alt-n` retrieves next - -* :kbd:`Return` while on any previous command retrieves that command - -* :kbd:`Alt-/` (Expand word) is also useful here - -.. index:: single: indentation - - -Syntax colors -------------- - -The coloring is applied in a background "thread," so you may occasionally see -uncolorized text. To change the color scheme, edit the ``[Colors]`` section in -:file:`config.txt`. - -Python syntax colors: - Keywords - orange - - Strings - green - - Comments - red - - Definitions - blue - -Shell colors: - Console output - brown - - stdout - blue - - stderr - dark green - - stdin - black - - -Command line usage -^^^^^^^^^^^^^^^^^^ - -:: - - idle.py [-c command] [-d] [-e] [-s] [-t title] [arg] ... - - -c command run this command - -d enable debugger - -e edit mode; arguments are files to be edited - -s run $IDLESTARTUP or $PYTHONSTARTUP first - -t title set title of shell window - -If there are arguments: - -#. If :option:`-e` is used, arguments are files opened for editing and - ``sys.argv`` reflects the arguments passed to IDLE itself. - -#. Otherwise, if :option:`-c` is used, all arguments are placed in - ``sys.argv[1:...]``, with ``sys.argv[0]`` set to ``'-c'``. - -#. Otherwise, if neither :option:`-e` nor :option:`-c` is used, the first - argument is a script which is executed with the remaining arguments in - ``sys.argv[1:...]`` and ``sys.argv[0]`` set to the script name. If the script - name is '-', no script is executed but an interactive Python session is started; - the arguments are still available in ``sys.argv``. - - -.. _other-gui-packages: - -Other Graphical User Interface Packages -======================================= - -There are an number of extension widget sets to :mod:`Tkinter`. - - -.. seealso:: - - `Python megawidgets <http://pmw.sourceforge.net/>`_ - is a toolkit for building high-level compound widgets in Python using the - :mod:`Tkinter` module. It consists of a set of base classes and a library of - flexible and extensible megawidgets built on this foundation. These megawidgets - include notebooks, comboboxes, selection widgets, paned widgets, scrolled - widgets, dialog windows, etc. Also, with the Pmw.Blt interface to BLT, the - busy, graph, stripchart, tabset and vector commands are be available. - - The initial ideas for Pmw were taken from the Tk ``itcl`` extensions ``[incr - Tk]`` by Michael McLennan and ``[incr Widgets]`` by Mark Ulferts. Several of the - megawidgets are direct translations from the itcl to Python. It offers most of - the range of widgets that ``[incr Widgets]`` does, and is almost as complete as - Tix, lacking however Tix's fast :class:`HList` widget for drawing trees. - - `Tkinter3000 Widget Construction Kit (WCK) <http://tkinter.effbot.org/>`_ - is a library that allows you to write new Tkinter widgets in pure Python. The - WCK framework gives you full control over widget creation, configuration, screen - appearance, and event handling. WCK widgets can be very fast and light-weight, - since they can operate directly on Python data structures, without having to - transfer data through the Tk/Tcl layer. - - .. % - -Other GUI packages are also available for Python: - - -.. seealso:: - - `wxPython <http://www.wxpython.org>`_ - wxPython is a cross-platform GUI toolkit for Python that is built around the - popular `wxWidgets <http://www.wxwidgets.org/>`_ C++ toolkit. It provides a - native look and feel for applications on Windows, Mac OS X, and Unix systems by - using each platform's native widgets where ever possible, (GTK+ on Unix-like - systems). In addition to an extensive set of widgets, wxPython provides classes - for online documentation and context sensitive help, printing, HTML viewing, - low-level device context drawing, drag and drop, system clipboard access, an - XML-based resource format and more, including an ever growing library of user- - contributed modules. Both the wxWidgets and wxPython projects are under active - development and continuous improvement, and have active and helpful user and - developer communities. - - `wxPython in Action <http://www.amazon.com/exec/obidos/ASIN/1932394621>`_ - The wxPython book, by Noel Rappin and Robin Dunn. - - PyQt - PyQt is a :program:`sip`\ -wrapped binding to the Qt toolkit. Qt is an - extensive C++ GUI toolkit that is available for Unix, Windows and Mac OS X. - :program:`sip` is a tool for generating bindings for C++ libraries as Python - classes, and is specifically designed for Python. An online manual is available - at http://www.opendocspublishing.com/pyqt/ (errata are located at - http://www.valdyas.org/python/book.html). - - `PyKDE <http://www.riverbankcomputing.co.uk/pykde/index.php>`_ - PyKDE is a :program:`sip`\ -wrapped interface to the KDE desktop libraries. KDE - is a desktop environment for Unix computers; the graphical components are based - on Qt. - - `FXPy <http://fxpy.sourceforge.net/>`_ - is a Python extension module which provides an interface to the `FOX - <http://www.cfdrc.com/FOX/fox.html>`_ GUI. FOX is a C++ based Toolkit for - developing Graphical User Interfaces easily and effectively. It offers a wide, - and growing, collection of Controls, and provides state of the art facilities - such as drag and drop, selection, as well as OpenGL widgets for 3D graphical - manipulation. FOX also implements icons, images, and user-convenience features - such as status line help, and tooltips. - - Even though FOX offers a large collection of controls already, FOX leverages C++ - to allow programmers to easily build additional Controls and GUI elements, - simply by taking existing controls, and creating a derived class which simply - adds or redefines the desired behavior. - - `PyGTK <http://www.daa.com.au/~james/software/pygtk/>`_ - is a set of bindings for the `GTK <http://www.gtk.org/>`_ widget set. It - provides an object oriented interface that is slightly higher level than the C - one. It automatically does all the type casting and reference counting that you - would have to do normally with the C API. There are also `bindings - <http://www.daa.com.au/~james/gnome/>`_ to `GNOME <http://www.gnome.org>`_, and - a `tutorial - <http://laguna.fmedic.unam.mx/~daniel/pygtutorial/pygtutorial/index.html>`_ is - available. - -.. % XXX Reference URLs that compare the different UI packages - Modified: doctools/trunk/Doc-3k/library/xml.dom.minidom.rst ============================================================================== --- doctools/trunk/Doc-3k/library/xml.dom.minidom.rst (original) +++ doctools/trunk/Doc-3k/library/xml.dom.minidom.rst Thu Aug 2 17:44:40 2007 @@ -108,7 +108,7 @@ The W3C recommendation for the DOM supported by :mod:`xml.dom.minidom`. -.. _dom-objects: +.. _minidom-objects: DOM Objects ----------- Modified: doctools/trunk/Doc-3k/reference/compound_stmts.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/compound_stmts.rst (original) +++ doctools/trunk/Doc-3k/reference/compound_stmts.rst Thu Aug 2 17:44:40 2007 @@ -270,7 +270,7 @@ :func:`sys.exc_info` returns a 3-tuple consisting of: ``exc_type`` receives the object identifying the exception; ``exc_value`` receives the exception's parameter; ``exc_traceback`` receives a traceback object (see section -:ref:`traceback`) identifying the point in the program where the exception +:ref:`types`) identifying the point in the program where the exception occurred. :func:`sys.exc_info` values are restored to their previous values (before the call) when returning from a function that handled an exception. Modified: doctools/trunk/Doc-3k/reference/datamodel.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/datamodel.rst (original) +++ doctools/trunk/Doc-3k/reference/datamodel.rst Thu Aug 2 17:44:40 2007 @@ -989,8 +989,6 @@ can implement a Jump command (aka Set Next Statement) by writing to f_lineno. Traceback objects - .. _traceback: - .. index:: object: traceback pair: stack; trace Modified: doctools/trunk/Doc-3k/reference/simple_stmts.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/simple_stmts.rst (original) +++ doctools/trunk/Doc-3k/reference/simple_stmts.rst Thu Aug 2 17:44:40 2007 @@ -500,7 +500,7 @@ .. index:: object: traceback If a third object is present and not ``None``, it must be a traceback object -(see section :ref:`traceback`), and it is substituted instead of the current +(see section :ref:`types`), and it is substituted instead of the current location as the place where the exception occurred. If the third object is present and not a traceback object or ``None``, a :exc:`TypeError` exception is raised. The three-expression form of :keyword:`raise` is useful to re-raise an

1 0

Aug. 2, 2007

Author: georg.brandl Date: Thu Aug 2 16:49:09 2007 New Revision: 56669 Modified: doctools/trunk/Doc-26/c-api/concrete.rst doctools/trunk/Doc-26/c-api/newtypes.rst doctools/trunk/Doc-26/extending/extending.rst doctools/trunk/Doc-26/install/index.rst doctools/trunk/Doc-26/library/__builtin__.rst doctools/trunk/Doc-26/library/csv.rst doctools/trunk/Doc-26/library/ctypes.rst doctools/trunk/Doc-26/library/datetime.rst doctools/trunk/Doc-26/library/functions.rst doctools/trunk/Doc-26/library/intro.rst doctools/trunk/Doc-26/library/logging.rst doctools/trunk/Doc-26/library/optparse.rst doctools/trunk/Doc-26/library/os.rst doctools/trunk/Doc-26/library/pyexpat.rst doctools/trunk/Doc-26/library/shlex.rst doctools/trunk/Doc-26/library/socket.rst doctools/trunk/Doc-26/library/sqlite3.rst doctools/trunk/Doc-26/library/stdtypes.rst doctools/trunk/Doc-26/library/string.rst doctools/trunk/Doc-26/library/sys.rst doctools/trunk/Doc-26/library/tarfile.rst doctools/trunk/Doc-26/library/tkinter.rst doctools/trunk/Doc-26/library/urlparse.rst doctools/trunk/Doc-26/library/userdict.rst doctools/trunk/Doc-26/library/xml.dom.rst doctools/trunk/Doc-26/library/xml.sax.reader.rst doctools/trunk/Doc-26/library/zipfile.rst doctools/trunk/Doc-26/library/zipimport.rst doctools/trunk/Doc-26/maclib/using.rst doctools/trunk/Doc-26/reference/datamodel.rst doctools/trunk/Doc-26/reference/expressions.rst doctools/trunk/Doc-26/reference/lexical_analysis.rst doctools/trunk/Doc-26/reference/simple_stmts.rst doctools/trunk/Doc-26/tutorial/errors.rst doctools/trunk/Doc-26/tutorial/modules.rst doctools/trunk/Doc-3k/c-api/concrete.rst doctools/trunk/Doc-3k/c-api/newtypes.rst doctools/trunk/Doc-3k/extending/extending.rst doctools/trunk/Doc-3k/install/index.rst doctools/trunk/Doc-3k/library/__builtin__.rst doctools/trunk/Doc-3k/library/csv.rst doctools/trunk/Doc-3k/library/ctypes.rst doctools/trunk/Doc-3k/library/datetime.rst doctools/trunk/Doc-3k/library/functions.rst doctools/trunk/Doc-3k/library/intro.rst doctools/trunk/Doc-3k/library/logging.rst doctools/trunk/Doc-3k/library/optparse.rst doctools/trunk/Doc-3k/library/os.rst doctools/trunk/Doc-3k/library/pyexpat.rst doctools/trunk/Doc-3k/library/shlex.rst doctools/trunk/Doc-3k/library/socket.rst doctools/trunk/Doc-3k/library/sqlite3.rst doctools/trunk/Doc-3k/library/stdtypes.rst doctools/trunk/Doc-3k/library/string.rst doctools/trunk/Doc-3k/library/sys.rst doctools/trunk/Doc-3k/library/tarfile.rst doctools/trunk/Doc-3k/library/tkinter.rst doctools/trunk/Doc-3k/library/urlparse.rst doctools/trunk/Doc-3k/library/userdict.rst doctools/trunk/Doc-3k/library/xml.dom.rst doctools/trunk/Doc-3k/library/xml.sax.reader.rst doctools/trunk/Doc-3k/library/zipfile.rst doctools/trunk/Doc-3k/library/zipimport.rst doctools/trunk/Doc-3k/maclib/using.rst doctools/trunk/Doc-3k/reference/datamodel.rst doctools/trunk/Doc-3k/reference/expressions.rst doctools/trunk/Doc-3k/reference/lexical_analysis.rst doctools/trunk/Doc-3k/tutorial/errors.rst doctools/trunk/Doc-3k/tutorial/modules.rst Log: Remove redundant section titles after :ref:s. Modified: doctools/trunk/Doc-26/c-api/concrete.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/concrete.rst (original) +++ doctools/trunk/Doc-26/c-api/concrete.rst Thu Aug 2 16:49:09 2007 @@ -1721,9 +1721,8 @@ .. index:: single: PyBufferProcs -More information on the buffer interface is provided in the section "Buffer -Object Structures" (section :ref:`buffer-structs`), under the description for -:ctype:`PyBufferProcs`. +More information on the buffer interface is provided in the section +:ref:`buffer-structs`, under the description for :ctype:`PyBufferProcs`. A "buffer object" is defined in the :file:`bufferobject.h` header (included by :file:`Python.h`). These objects look very similar to string objects at the Modified: doctools/trunk/Doc-26/c-api/newtypes.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/newtypes.rst (original) +++ doctools/trunk/Doc-26/c-api/newtypes.rst Thu Aug 2 16:49:09 2007 @@ -701,8 +701,8 @@ .. cmember:: PyBufferProcs* PyTypeObject.tp_as_buffer Pointer to an additional structure that contains fields relevant only to objects - which implement the buffer interface. These fields are documented in "Buffer - Object Structures" (section :ref:`buffer-structs`). + which implement the buffer interface. These fields are documented in + :ref:`buffer-structs`. The :attr:`tp_as_buffer` field is not inherited, but the contained fields are inherited individually. Modified: doctools/trunk/Doc-26/extending/extending.rst ============================================================================== --- doctools/trunk/Doc-26/extending/extending.rst (original) +++ doctools/trunk/Doc-26/extending/extending.rst Thu Aug 2 16:49:09 2007 @@ -457,15 +457,14 @@ } This function must be registered with the interpreter using the -:const:`METH_VARARGS` flag; this is described in section :ref:`methodtable`, -"The Module's Method Table and Initialization Function." The +:const:`METH_VARARGS` flag; this is described in section :ref:`methodtable`. The :cfunc:`PyArg_ParseTuple` function and its arguments are documented in section -:ref:`parsetuple`, "Extracting Parameters in Extension Functions." +:ref:`parsetuple`. The macros :cfunc:`Py_XINCREF` and :cfunc:`Py_XDECREF` increment/decrement the reference count of an object and are safe in the presence of *NULL* pointers (but note that *temp* will not be *NULL* in this context). More info on them -in section :ref:`refcounts`, "Reference Counts." +in section :ref:`refcounts`. .. index:: single: PyEval_CallObject() Modified: doctools/trunk/Doc-26/install/index.rst ============================================================================== --- doctools/trunk/Doc-26/install/index.rst (original) +++ doctools/trunk/Doc-26/install/index.rst Thu Aug 2 16:49:09 2007 @@ -42,7 +42,7 @@ .. % end{latexonly} -.. _intro: +.. _inst-intro: Introduction ============ @@ -67,7 +67,7 @@ the Distributing Python Modules (XXX reference: ../dist/dist.html) manual. -.. _trivial-install: +.. _inst-trivial-install: Best case: trivial installation ------------------------------- @@ -95,7 +95,7 @@ modules from standard source distributions. -.. _new-standard: +.. _inst-new-standard: The new standard: Distutils --------------------------- @@ -119,12 +119,12 @@ get out of this manual. -.. _standard-install: +.. _inst-standard-install: Standard Build and Install ========================== -As described in section :ref:`new-standard`, building and installing a module +As described in section :ref:`inst-new-standard`, building and installing a module distribution using the Distutils is usually one simple command:: python setup.py install @@ -134,7 +134,7 @@ a :command:`Terminal` window to get a shell prompt. -.. _platform-variations: +.. _inst-platform-variations: Platform variations ------------------- @@ -159,7 +159,7 @@ python setup.py install -.. _splitting-up: +.. _inst-splitting-up: Splitting the job up -------------------- @@ -189,7 +189,7 @@ you'll run lots of individual Distutils commands on their own. -.. _how-build-works: +.. _inst-how-build-works: How building works ------------------ @@ -203,7 +203,7 @@ python setup.py build --build-base=/tmp/pybuild/foo-1.0 (Or you could do this permanently with a directive in your system or personal -Distutils configuration file; see section :ref:`config-files`.) Normally, this +Distutils configuration file; see section :ref:`inst-config-files`.) Normally, this isn't necessary. The default layout for the build tree is as follows:: @@ -228,7 +228,7 @@ of installing Python modules and applications. -.. _how-install-works: +.. _inst-how-install-works: How installation works ---------------------- @@ -290,12 +290,12 @@ If you don't want to install modules to the standard location, or if you don't have permission to write there, then you need to read about alternate -installations in section :ref:`alt-install`. If you want to customize your -installation directories more heavily, see section :ref:`custom-install` on +installations in section :ref:`inst-alt-install`. If you want to customize your +installation directories more heavily, see section :ref:`inst-custom-install` on custom installations. -.. _alt-install: +.. _inst-alt-install: Alternate Installation ====================== @@ -317,7 +317,7 @@ you. -.. _alt-install-prefix: +.. _inst-alt-install-prefix: Alternate installation: the home scheme --------------------------------------- @@ -358,7 +358,7 @@ The :option:`--home` option used to be supported only on Unix. -.. _alt-install-home: +.. _inst-alt-install-home: Alternate installation: Unix (the prefix scheme) ------------------------------------------------ @@ -430,7 +430,7 @@ alternate Python installation, this is immaterial.) -.. _alt-install-windows: +.. _inst-alt-install-windows: Alternate installation: Windows (the prefix scheme) --------------------------------------------------- @@ -461,13 +461,13 @@ +------------------------------+---------------------------+-----------------------------+ -.. _custom-install: +.. _inst-custom-install: Custom Installation =================== Sometimes, the alternate installation schemes described in section -:ref:`alt-install` just don't do what you want. You might want to tweak just +:ref:`inst-alt-install` just don't do what you want. You might want to tweak just one or two directories while keeping everything under the same base directory, or you might want to completely redefine the installation scheme. In either case, you're creating a *custom installation scheme*. @@ -513,7 +513,7 @@ The specified installation directories are relative to :file:`{prefix}`. Of course, you also have to ensure that these directories are in Python's module search path, such as by putting a :file:`.pth` file in :file:`{prefix}`. See -section :ref:`search-path` to find out how to modify Python's search path. +section :ref:`inst-search-path` to find out how to modify Python's search path. If you want to define an entire installation scheme, you just have to supply all of the installation directory options. The recommended way to do this is to @@ -548,7 +548,7 @@ Obviously, specifying the entire installation scheme every time you install a new module distribution would be very tedious. Thus, you can put these options -into your Distutils config file (see section :ref:`config-files`):: +into your Distutils config file (see section :ref:`inst-config-files`):: [install] install-base=$HOME @@ -582,7 +582,7 @@ the Distutils additionally define a few extra variables that may not be in your environment, such as ``$PLAT``. (And of course, on systems that don't have environment variables, such as Mac OS 9, the configuration variables supplied by -the Distutils are the only ones you can use.) See section :ref:`config-files` +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 @@ -591,7 +591,7 @@ .. % XXX I'm not sure where this section should go. -.. _search-path: +.. _inst-search-path: Modifying Python's Search Path ------------------------------ @@ -670,7 +670,7 @@ can modify it by adding or removing entries. -.. _config-files: +.. _inst-config-files: Distutils Configuration Files ============================= @@ -685,7 +685,7 @@ by "later" files. -.. _config-filenames: +.. _inst-config-filenames: Location and names of config files ---------------------------------- @@ -748,7 +748,7 @@ Distutils make no attempt to guess your home directory on Windows.) -.. _config-syntax: +.. _inst-config-syntax: Syntax of config files ---------------------- @@ -802,7 +802,7 @@ See also the "Reference" section of the "Distributing Python Modules" manual. -.. _building-ext: +.. _inst-building-ext: Building Extensions: Tips and Tricks ==================================== @@ -815,7 +815,7 @@ to override the usual Distutils behaviour. -.. _tweak-flags: +.. _inst-tweak-flags: Tweaking compiler/linker flags ------------------------------ @@ -885,7 +885,7 @@ the compiler flags specified in the :file:`Setup` file. -.. _non-ms-compilers: +.. _inst-non-ms-compilers: Using non-Microsoft compilers on Windows ---------------------------------------- @@ -932,7 +932,7 @@ If you want to use the Borland C++ compiler as the default, you could specify this in your personal or system-wide configuration file for Distutils (see -section :ref:`config-files`.) +section :ref:`inst-config-files`.) .. seealso:: @@ -998,7 +998,7 @@ If you want to use any of these options/compilers as default, you should consider to write it in your personal or system-wide configuration file for -Distutils (see section :ref:`config-files`.) +Distutils (see section :ref:`inst-config-files`.) .. seealso:: Modified: doctools/trunk/Doc-26/library/__builtin__.rst ============================================================================== --- doctools/trunk/Doc-26/library/__builtin__.rst (original) +++ doctools/trunk/Doc-26/library/__builtin__.rst Thu Aug 2 16:49:09 2007 @@ -8,7 +8,7 @@ This module provides direct access to all 'built-in' identifiers of Python; for example, ``__builtin__.open`` is the full name for the built-in function -:func:`open`. See chapter :ref:`builtin`, "Built-in Objects." +:func:`open`. See chapter :ref:`builtin`. This module is not normally accessed explicitly by most applications, but can be useful in modules that provide objects with the same name as a built-in value, Modified: doctools/trunk/Doc-26/library/csv.rst ============================================================================== --- doctools/trunk/Doc-26/library/csv.rst (original) +++ doctools/trunk/Doc-26/library/csv.rst Thu Aug 2 16:49:09 2007 @@ -72,7 +72,7 @@ :func:`list_dialects` function. The other optional *fmtparam* keyword arguments can be given to override individual formatting parameters in the current dialect. For full details about the dialect and formatting parameters, see - section :ref:`csv-fmt-params`, "Dialects and Formatting Parameters". + section :ref:`csv-fmt-params`. All data read are returned as strings. No automatic data type conversion is performed. @@ -99,7 +99,7 @@ :func:`list_dialects` function. The other optional *fmtparam* keyword arguments can be given to override individual formatting parameters in the current dialect. For full details about the dialect and formatting parameters, see - section :ref:`csv-fmt-params`, "Dialects and Formatting Parameters". To make it + section :ref:`csv-fmt-params`. To make it as easy as possible to interface with modules which implement the DB API, the value :const:`None` is written as the empty string. While this isn't a reversible transformation, it makes it easier to dump SQL NULL data values to @@ -113,8 +113,7 @@ dialect can be specified either by passing a sub-class of :class:`Dialect`, or by *fmtparam* keyword arguments, or both, with keyword arguments overriding parameters of the dialect. For full details about the dialect and formatting - parameters, see section :ref:`csv-fmt-params`, "Dialects and Formatting - Parameters". + parameters, see section :ref:`csv-fmt-params`. .. function:: unregister_dialect(name) Modified: doctools/trunk/Doc-26/library/ctypes.rst ============================================================================== --- doctools/trunk/Doc-26/library/ctypes.rst (original) +++ doctools/trunk/Doc-26/library/ctypes.rst Thu Aug 2 16:49:09 2007 @@ -2359,6 +2359,6 @@ Arrays and pointers ^^^^^^^^^^^^^^^^^^^ -Not yet written - please see section :ref:`ctypes-pointers`, pointers and -section :ref:`ctypes-arrays`, arrays in the tutorial. +Not yet written - please see the sections :ref:`ctypes-pointers` and +section :ref:`ctypes-arrays` in the tutorial. Modified: doctools/trunk/Doc-26/library/datetime.rst ============================================================================== --- doctools/trunk/Doc-26/library/datetime.rst (original) +++ doctools/trunk/Doc-26/library/datetime.rst Thu Aug 2 16:49:09 2007 @@ -491,7 +491,7 @@ Return a string representing the date, controlled by an explicit format string. Format codes referring to hours, minutes or seconds will see 0 values. See - section :ref:`strftime-behavior` -- :meth:`strftime` behavior. + section :ref:`strftime-behavior`. .. _datetime-datetime: @@ -931,7 +931,7 @@ .. method:: datetime.strftime(format) Return a string representing the date and time, controlled by an explicit format - string. See section :ref:`strftime-behavior` -- :meth:`strftime` behavior. + string. See section :ref:`strftime-behavior`. .. _datetime-time: @@ -1056,7 +1056,7 @@ .. method:: time.strftime(format) Return a string representing the time, controlled by an explicit format string. - See section :ref:`strftime-behavior` -- :meth:`strftime` behavior. + See section :ref:`strftime-behavior`. .. method:: time.utcoffset() Modified: doctools/trunk/Doc-26/library/functions.rst ============================================================================== --- doctools/trunk/Doc-26/library/functions.rst (original) +++ doctools/trunk/Doc-26/library/functions.rst Thu Aug 2 16:49:09 2007 @@ -419,10 +419,9 @@ .. function:: file(filename[, mode[, bufsize]]) - Constructor function for the :class:`file` type, described further in section - :ref:`bltin-file-objects`, "File Objects (XXX reference: bltin-file- - objects.html)". The constructor's arguments are the same as those of the - :func:`open` built-in function described below. + Constructor function for the :class:`file` type, described further in section + :ref:`bltin-file-objects`. The constructor's arguments are the same as those + of the :func:`open` built-in function described below. When opening a file, it's preferable to use :func:`open` instead of invoking this constructor directly. :class:`file` is more suited to type testing (for @@ -721,11 +720,10 @@ .. function:: open(filename[, mode[, bufsize]]) - Open a file, returning an object of the :class:`file` type described in section - :ref:`bltin-file-objects`, "File Objects (XXX reference: bltin-file- - objects.html)". If the file cannot be opened, :exc:`IOError` is raised. When - opening a file, it's preferable to use :func:`open` instead of invoking the - :class:`file` constructor directly. + Open a file, returning an object of the :class:`file` type described in + section :ref:`bltin-file-objects`. If the file cannot be opened, + :exc:`IOError` is raised. When opening a file, it's preferable to use + :func:`open` instead of invoking the :class:`file` constructor directly. The first two arguments are the same as for ``stdio``'s :cfunc:`fopen`: *filename* is the file name to be opened, and *mode* is a string indicating how Modified: doctools/trunk/Doc-26/library/intro.rst ============================================================================== --- doctools/trunk/Doc-26/library/intro.rst (original) +++ doctools/trunk/Doc-26/library/intro.rst Thu Aug 2 16:49:09 2007 @@ -44,9 +44,8 @@ function, module or term in the index (in the back). And finally, if you enjoy learning about random subjects, you choose a random page number (see module :mod:`random`) and read a section or two. Regardless of the order in which you -read the sections of this manual, it helps to start with chapter -:ref:`builtin`, "Built-in Types, Exceptions and Functions," as the remainder of -the manual assumes familiarity with this material. +read the sections of this manual, it helps to start with chapter :ref:`builtin`, +as the remainder of the manual assumes familiarity with this material. Let the show begin! Modified: doctools/trunk/Doc-26/library/logging.rst ============================================================================== --- doctools/trunk/Doc-26/library/logging.rst (original) +++ doctools/trunk/Doc-26/library/logging.rst Thu Aug 2 16:49:09 2007 @@ -1483,8 +1483,8 @@ of the :class:`LogRecord` attributes - such as the default value mentioned above making use of the fact that the user's message and arguments are pre-formatted into a :class:`LogRecord`'s *message* attribute. This format string contains -standard python %-style mapping keys. See section :ref:`typesseq-strings`, -"String Formatting Operations," for more information on string formatting. +standard python %-style mapping keys. See section :ref:`typesseq-strings` +for more information on string formatting. Currently, the useful mapping keys in a :class:`LogRecord` are: Modified: doctools/trunk/Doc-26/library/optparse.rst ============================================================================== --- doctools/trunk/Doc-26/library/optparse.rst (original) +++ doctools/trunk/Doc-26/library/optparse.rst Thu Aug 2 16:49:09 2007 @@ -309,7 +309,7 @@ Actions tell :mod:`optparse` what to do when it encounters an option on the command line. There is a fixed set of actions hard-coded into :mod:`optparse`; adding new actions is an advanced topic covered in section -:ref:`optparse-extending-optparse`, Extending :mod:`optparse`. Most actions tell +:ref:`optparse-extending-optparse`. Most actions tell :mod:`optparse` to store a value in some variable---for example, take a string from the command line and store it in an attribute of ``options``. @@ -369,8 +369,7 @@ default destination for ``"-f"`` is ``f``. :mod:`optparse` also includes built-in ``long`` and ``complex`` types. Adding -types is covered in section :ref:`optparse-extending-optparse`, Extending -:mod:`optparse`. +types is covered in section :ref:`optparse-extending-optparse`. .. _optparse-handling-boolean-options: @@ -415,7 +414,7 @@ call a specified function These are covered in section :ref:`optparse-reference-guide`, Reference Guide -and section :ref:`optparse-option-callbacks`, Option Callbacks. +and section :ref:`optparse-option-callbacks`. .. _optparse-default-values: @@ -704,8 +703,7 @@ ``conflict_handler`` (default: ``"error"``) Specifies what to do when options with conflicting option strings are added to - the parser; see section :ref:`optparse-conflicts-between-options`, Conflicts - between options. + the parser; see section :ref:`optparse-conflicts-between-options`. ``description`` (default: ``None``) A paragraph of text giving a brief overview of your program. :mod:`optparse` @@ -734,8 +732,7 @@ There are several ways to populate the parser with options. The preferred way is by using ``OptionParser.add_option()``, as shown in section -:ref:`optparse-tutorial`, the tutorial. :meth:`add_option` can be called in one -of two ways: +:ref:`optparse-tutorial`. :meth:`add_option` can be called in one of two ways: * pass it an Option instance (as returned by :func:`make_option`) @@ -986,7 +983,7 @@ func(option, opt_str, value, parser, *args, **kwargs) - See section :ref:`optparse-option-callbacks`, Option Callbacks for more detail. + See section :ref:`optparse-option-callbacks` for more detail. * :attr:`help` @@ -1083,9 +1080,9 @@ * ``callback`` - For options with action ``"callback"``, the callable to call when this option is - seen. See section :ref:`optparse-option-callbacks`, Option Callbacks for detail - on the arguments passed to ``callable``. + For options with action ``"callback"``, the callable to call when this option + is seen. See section :ref:`optparse-option-callbacks` for detail on the + arguments passed to ``callable``. * ``callback_args``, ``callback_kwargs`` @@ -1102,7 +1099,7 @@ * ``metavar`` (default: derived from option strings) Stand-in for the option argument(s) to use when printing help text. See section - :ref:`optparse-tutorial`, the tutorial for an example. + :ref:`optparse-tutorial` for an example. .. _optparse-standard-option-types: @@ -1112,7 +1109,7 @@ :mod:`optparse` has six built-in option types: ``string``, ``int``, ``long``, ``choice``, ``float`` and ``complex``. If you need to add new option types, see -section :ref:`optparse-extending-optparse`, Extending :mod:`optparse`. +section :ref:`optparse-extending-optparse`. Arguments to string options are not checked or converted in any way: the text on the command line is stored in the destination (or passed to the callback) as-is. Modified: doctools/trunk/Doc-26/library/os.rst ============================================================================== --- doctools/trunk/Doc-26/library/os.rst (original) +++ doctools/trunk/Doc-26/library/os.rst Thu Aug 2 16:49:09 2007 @@ -122,8 +122,7 @@ getcwd() :noindex: - These functions are described in "Files and Directories" (section - :ref:`os-file-dir`). + These functions are described in :ref:`os-file-dir`. .. function:: ctermid() @@ -422,8 +421,7 @@ available on Unix. For a discussion of possible deadlock conditions related to the use of these -functions, see "Flow Control Issues (XXX reference: popen2-flow-control.html)" -(section :ref:`popen2-flow-control`). +functions, see :ref:`popen2-flow-control`. .. function:: popen2(cmd[, mode[, bufsize]]) Modified: doctools/trunk/Doc-26/library/pyexpat.rst ============================================================================== --- doctools/trunk/Doc-26/library/pyexpat.rst (original) +++ doctools/trunk/Doc-26/library/pyexpat.rst Thu Aug 2 16:49:09 2007 @@ -39,8 +39,7 @@ .. exception:: ExpatError The exception raised when Expat reports an error. See section - :ref:`expaterror-objects`, "ExpatError Exceptions," for more information on - interpreting Expat errors. + :ref:`expaterror-objects` for more information on interpreting Expat errors. .. exception:: error Modified: doctools/trunk/Doc-26/library/shlex.rst ============================================================================== --- doctools/trunk/Doc-26/library/shlex.rst (original) +++ doctools/trunk/Doc-26/library/shlex.rst Thu Aug 2 16:49:09 2007 @@ -58,7 +58,7 @@ was introduced in Python 2.3, and defines the operational mode. When *posix* is not true (default), the :class:`shlex` instance will operate in compatibility mode. When operating in POSIX mode, :class:`shlex` will try to be as close as - possible to the POSIX shell parsing rules. See section :ref:`shlex-objects`. + possible to the POSIX shell parsing rules. .. seealso:: Modified: doctools/trunk/Doc-26/library/socket.rst ============================================================================== --- doctools/trunk/Doc-26/library/socket.rst (original) +++ doctools/trunk/Doc-26/library/socket.rst Thu Aug 2 16:49:09 2007 @@ -571,13 +571,12 @@ .. index:: single: I/O control; buffering Return a :dfn:`file object` associated with the socket. (File objects are - described in :ref:`bltin-file-objects`, "File Objects.") The file object + described in :ref:`bltin-file-objects`.) The file object references a :cfunc:`dup`\ ped version of the socket file descriptor, so the 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 "Built-in Functions" (section :ref:`built-in-funcs`) - for more information. + :func:`file` function; see :ref:`built-in-funcs` for more information. .. method:: socket.recv(bufsize[, flags]) Modified: doctools/trunk/Doc-26/library/sqlite3.rst ============================================================================== --- doctools/trunk/Doc-26/library/sqlite3.rst (original) +++ doctools/trunk/Doc-26/library/sqlite3.rst Thu Aug 2 16:49:09 2007 @@ -227,8 +227,8 @@ .. attribute:: Connection.isolation_level Get or set the current isolation level. None for autocommit mode or one of - "DEFERRED", "IMMEDIATE" or "EXLUSIVE". See "Controlling Transactions", section - :ref:`sqlite3-controlling-transactions`, for a more detailed explanation. + "DEFERRED", "IMMEDIATE" or "EXLUSIVE". See section + :ref:`sqlite3-controlling-transactions` for a more detailed explanation. .. method:: Connection.cursor([cursorClass]) @@ -629,9 +629,8 @@ * Explicitly via the column name -Both ways are described in "Module Constants", section -:ref:`sqlite3-module-contents`, in the entries for the constants -:const:`PARSE_DECLTYPES` and :const:`PARSE_COLNAMES`. +Both ways are described in section :ref:`sqlite3-module-contents`, in the entries +for the constants :const:`PARSE_DECLTYPES` and :const:`PARSE_COLNAMES`. The following example illustrates both approaches. Modified: doctools/trunk/Doc-26/library/stdtypes.rst ============================================================================== --- doctools/trunk/Doc-26/library/stdtypes.rst (original) +++ doctools/trunk/Doc-26/library/stdtypes.rst Thu Aug 2 16:49:09 2007 @@ -341,7 +341,7 @@ for well-defined conversions. (3) - See section :ref:`built-in-funcs`, "Built-in Functions," for a full description. + See :ref:`built-in-funcs` for a full description. (4) Complex floor division operator, modulo operator, and :func:`divmod`. @@ -1739,9 +1739,9 @@ File objects are implemented using C's ``stdio`` package and can be created with the built-in constructor :func:`file` described in section -:ref:`built-in-funcs`, "Built-in Functions." [#]_ 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 objects. +:ref:`built-in-funcs`. [#]_ 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 objects. When a file operation fails for an I/O-related reason, the exception :exc:`IOError` is raised. This includes situations where the operation is not @@ -2366,4 +2366,3 @@ might matter, for example, if you want to make an exact copy of a file while scanning its lines) to tell whether the last line of a file ended in a newline or not (yes this happens!). - Modified: doctools/trunk/Doc-26/library/string.rst ============================================================================== --- doctools/trunk/Doc-26/library/string.rst (original) +++ doctools/trunk/Doc-26/library/string.rst Thu Aug 2 16:49:09 2007 @@ -245,10 +245,9 @@ --------------------------- The following list of functions are also defined as methods of string and -Unicode objects; see "String Methods" (section :ref:`string-methods`) for more -information on those. You should consider these functions as deprecated, -although they will not be removed until Python 3.0. The functions defined in -this module are: +Unicode objects; see section :ref:`string-methods` for more information on +those. You should consider these functions as deprecated, although they will +not be removed until Python 3.0. The functions defined in this module are: .. function:: atof(s) Modified: doctools/trunk/Doc-26/library/sys.rst ============================================================================== --- doctools/trunk/Doc-26/library/sys.rst (original) +++ doctools/trunk/Doc-26/library/sys.rst Thu Aug 2 16:49:09 2007 @@ -365,7 +365,7 @@ Their intended use is to allow an interactive user to import a debugger module and engage in post-mortem debugging without having to re-execute the command that caused the error. (Typical use is ``import pdb; pdb.pm()`` to enter the - post-mortem debugger; see chapter :ref:`debugger`, "The Python Debugger," for + post-mortem debugger; see chapter :ref:`debugger` for more information.) The meaning of the variables is the same as that of the return values from @@ -528,9 +528,9 @@ single: trace function single: debugger - Set the system's trace function, which allows you to implement a Python source - code debugger in Python. See section :ref:`debugger-hooks`, "How It Works," in - the chapter on the Python debugger. The function is thread-specific; for a + Set the system's trace function, which allows you to implement a Python + source code debugger in Python. See section :ref:`debugger-hooks` in the + chapter on the Python debugger. The function is thread-specific; for a debugger to support multiple threads, it must be registered using :func:`settrace` for each thread being debugged. Modified: doctools/trunk/Doc-26/library/tarfile.rst ============================================================================== --- doctools/trunk/Doc-26/library/tarfile.rst (original) +++ doctools/trunk/Doc-26/library/tarfile.rst Thu Aug 2 16:49:09 2007 @@ -37,7 +37,7 @@ Return a :class:`TarFile` object for the pathname *name*. For detailed information on :class:`TarFile` objects and the keyword arguments that are - allowed, see TarFile Objects (section :ref:`tarfile-objects`). + allowed, see :ref:`tarfile-objects`. *mode* has to be a string of the form ``'filemode[:compression]'``, it defaults to ``'r'``. Here is a full list of mode combinations: @@ -75,14 +75,14 @@ For special purposes, there is a second format for *mode*: ``'filemode|[compression]'``. :func:`open` will return a :class:`TarFile` - object that processes its data as a stream of blocks. No random seeking will be - done on the file. If given, *fileobj* may be any object that has a :meth:`read` - or :meth:`write` method (depending on the *mode*). *bufsize* specifies the - blocksize and defaults to ``20 * 512`` bytes. Use this variant in combination - with e.g. ``sys.stdin``, a socket file object or a tape device. However, such a - :class:`TarFile` object is limited in that it does not allow to be accessed - randomly, see "Examples" (section :ref:`tar-examples`). The currently possible - modes: + object that processes its data as a stream of blocks. No random seeking will + be done on the file. If given, *fileobj* may be any object that has a + :meth:`read` or :meth:`write` method (depending on the *mode*). *bufsize* + specifies the blocksize and defaults to ``20 * 512`` bytes. Use this variant + in combination with e.g. ``sys.stdin``, a socket file object or a tape + device. However, such a :class:`TarFile` object is limited in that it does + not allow to be accessed randomly, see :ref:`tar-examples`. The currently + possible modes: +-------------+--------------------------------------------+ | Mode | Action | @@ -112,8 +112,7 @@ .. class:: TarFile Class for reading and writing tar archives. Do not use this class directly, - better use :func:`open` instead. See "TarFile Objects" (section - :ref:`tarfile-objects`). + better use :func:`open` instead. See :ref:`tarfile-objects`. .. function:: is_tarfile(name) @@ -221,7 +220,7 @@ archive is a sequence of blocks. An archive member (a stored file) is made up of a header block followed by data blocks. It is possible to store a file in a tar archive several times. Each archive member is represented by a :class:`TarInfo` -object, see TarInfo Objects (section :ref:`tarinfo-objects`) for details. +object, see :ref:`tarinfo-objects` for details. .. class:: TarFile(name=None, mode='r', fileobj=None, format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False, ignore_zeros=False, encoding=None, errors=None, pax_headers=None, debug=0, errorlevel=0) Modified: doctools/trunk/Doc-26/library/tkinter.rst ============================================================================== --- doctools/trunk/Doc-26/library/tkinter.rst (original) +++ doctools/trunk/Doc-26/library/tkinter.rst Thu Aug 2 16:49:09 2007 @@ -22,9 +22,8 @@ classes. In addition, the internal module :mod:`_tkinter` provides a threadsafe mechanism which allows Python and Tcl to interact. -Tk is not the only GUI for Python; see section :ref:`other-gui-packages`, "Other -User Interface Modules and Packages," for more information on other GUI toolkits -for Python. +Tk is not the only GUI for Python; see section :ref:`other-gui-packages` for +more information on other GUI toolkits for Python. .. % Other sections I have in mind are .. % Tkinter internals Modified: doctools/trunk/Doc-26/library/urlparse.rst ============================================================================== --- doctools/trunk/Doc-26/library/urlparse.rst (original) +++ doctools/trunk/Doc-26/library/urlparse.rst Thu Aug 2 16:49:09 2007 @@ -90,8 +90,8 @@ | | | if present | | +------------------+-------+--------------------------+----------------------+ - See section :ref:`urlparse-result-object`, "Results of :func:`urlparse` and - :func:`urlsplit`," for more information on the result object. + See section :ref:`urlparse-result-object` for more information on the result + object. .. versionchanged:: 2.5 Added attributes to return value. @@ -141,8 +141,8 @@ | | | if present | | +------------------+-------+-------------------------+----------------------+ - See section :ref:`urlparse-result-object`, "Results of :func:`urlparse` and - :func:`urlsplit`," for more information on the result object. + See section :ref:`urlparse-result-object` for more information on the result + object. .. versionadded:: 2.2 Modified: doctools/trunk/Doc-26/library/userdict.rst ============================================================================== --- doctools/trunk/Doc-26/library/userdict.rst (original) +++ doctools/trunk/Doc-26/library/userdict.rst Thu Aug 2 16:49:09 2007 @@ -177,8 +177,8 @@ hard to track down. In addition to supporting the methods and operations of string and Unicode -objects (see section :ref:`string-methods`, "String Methods"), -:class:`UserString` instances provide the following attribute: +objects (see section :ref:`string-methods`), :class:`UserString` instances +provide the following attribute: .. attribute:: MutableString.data Modified: doctools/trunk/Doc-26/library/xml.dom.rst ============================================================================== --- doctools/trunk/Doc-26/library/xml.dom.rst (original) +++ doctools/trunk/Doc-26/library/xml.dom.rst Thu Aug 2 16:49:09 2007 @@ -65,8 +65,7 @@ and OMG IDL. The Python mapping defined here is based in large part on the IDL version of the specification, but strict compliance is not required (though implementations are free to support the strict mapping from IDL). See section -:ref:`dom-conformance`, "Conformance," for a detailed discussion of mapping -requirements. +:ref:`dom-conformance` for a detailed discussion of mapping requirements. .. seealso:: @@ -173,40 +172,40 @@ strings. It is fairly rare that you must do this, however, so this usage is not yet documented. -+--------------------------------+---------------------------------+---------------------------------+ -| Interface | Section | Purpose | -+================================+=================================+=================================+ -| :class:`DOMImplementation` | :ref:`dom-implementation- | Interface to the underlying | -| | objects` | implementation. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`Node` | :ref:`dom-node-objects` | Base interface for most objects | -| | | in a document. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`NodeList` | :ref:`dom-nodelist-objects` | Interface for a sequence of | -| | | nodes. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`DocumentType` | :ref:`dom-documenttype-objects` | Information about the | -| | | declarations needed to process | -| | | a document. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`Document` | :ref:`dom-document-objects` | Object which represents an | -| | | entire document. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`Element` | :ref:`dom-element-objects` | Element nodes in the document | -| | | hierarchy. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`Attr` | :ref:`dom-attr-objects` | Attribute value nodes on | -| | | element nodes. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`Comment` | :ref:`dom-comment-objects` | Representation of comments in | -| | | the source document. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`Text` | :ref:`dom-text-objects` | Nodes containing textual | -| | | content from the document. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`ProcessingInstruction` | :ref:`dom-pi-objects` | Processing instruction | -| | | representation. | -+--------------------------------+---------------------------------+---------------------------------+ ++--------------------------------+-----------------------------------+---------------------------------+ +| Interface | Section | Purpose | ++================================+===================================+=================================+ +| :class:`DOMImplementation` | :ref:`dom-implementation-objects` | Interface to the underlying | +| | | implementation. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`Node` | :ref:`dom-node-objects` | Base interface for most objects | +| | | in a document. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`NodeList` | :ref:`dom-nodelist-objects` | Interface for a sequence of | +| | | nodes. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`DocumentType` | :ref:`dom-documenttype-objects` | Information about the | +| | | declarations needed to process | +| | | a document. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`Document` | :ref:`dom-document-objects` | Object which represents an | +| | | entire document. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`Element` | :ref:`dom-element-objects` | Element nodes in the document | +| | | hierarchy. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`Attr` | :ref:`dom-attr-objects` | Attribute value nodes on | +| | | element nodes. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`Comment` | :ref:`dom-comment-objects` | Representation of comments in | +| | | the source document. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`Text` | :ref:`dom-text-objects` | Nodes containing textual | +| | | content from the document. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`ProcessingInstruction` | :ref:`dom-pi-objects` | Processing instruction | +| | | representation. | ++--------------------------------+-----------------------------------+---------------------------------+ An additional section describes the exceptions defined for working with the DOM in Python. Modified: doctools/trunk/Doc-26/library/xml.sax.reader.rst ============================================================================== --- doctools/trunk/Doc-26/library/xml.sax.reader.rst (original) +++ doctools/trunk/Doc-26/library/xml.sax.reader.rst Thu Aug 2 16:49:09 2007 @@ -70,24 +70,23 @@ .. class:: AttributesImpl(attrs) - This is an implementation of the :class:`Attributes` interface (XXX reference: - attributes-objects.html) (see section :ref:`attributes-objects`). This is a - dictionary-like object which represents the element attributes in a - :meth:`startElement` call. In addition to the most useful dictionary operations, - it supports a number of other methods as described by the interface. Objects of - this class should be instantiated by readers; *attrs* must be a dictionary-like - object containing a mapping from attribute names to attribute values. + This is an implementation of the :class:`Attributes` interface (see section + :ref:`attributes-objects`). This is a dictionary-like object which + represents the element attributes in a :meth:`startElement` call. In addition + to the most useful dictionary operations, it supports a number of other + methods as described by the interface. Objects of this class should be + instantiated by readers; *attrs* must be a dictionary-like object containing + a mapping from attribute names to attribute values. .. class:: AttributesNSImpl(attrs, qnames) Namespace-aware variant of :class:`AttributesImpl`, which will be passed to :meth:`startElementNS`. It is derived from :class:`AttributesImpl`, but - understands attribute names as two-tuples of *namespaceURI* and *localname*. In - addition, it provides a number of methods expecting qualified names as they - appear in the original document. This class implements the - :class:`AttributesNS` interface (XXX reference: attributes-ns-objects.html) (see - section :ref:`attributes-ns-objects`). + understands attribute names as two-tuples of *namespaceURI* and + *localname*. In addition, it provides a number of methods expecting qualified + names as they appear in the original document. This class implements the + :class:`AttributesNS` interface (see section :ref:`attributes-ns-objects`). .. _xmlreader-objects: @@ -359,9 +358,9 @@ The :class:`AttributesNS` Interface ----------------------------------- -This interface is a subtype of the :class:`Attributes` interface (XXX reference: -attributes-objects.html) (see section :ref:`attributes-objects`). All methods -supported by that interface are also available on :class:`AttributesNS` objects. +This interface is a subtype of the :class:`Attributes` interface (see section +:ref:`attributes-objects`). All methods supported by that interface are also +available on :class:`AttributesNS` objects. The following methods are also available: Modified: doctools/trunk/Doc-26/library/zipfile.rst ============================================================================== --- doctools/trunk/Doc-26/library/zipfile.rst (original) +++ doctools/trunk/Doc-26/library/zipfile.rst Thu Aug 2 16:49:09 2007 @@ -40,8 +40,8 @@ .. class:: ZipFile - The class for reading and writing ZIP files. See "ZipFile Objects" (section - :ref:`zipfile-objects`) for constructor details. + The class for reading and writing ZIP files. See section + :ref:`zipfile-objects` for constructor details. .. class:: PyZipFile @@ -51,14 +51,14 @@ .. class:: ZipInfo([filename[, date_time]]) - Class used to represent information about a member of an archive. Instances of - this class are returned by the :meth:`getinfo` and :meth:`infolist` methods of - :class:`ZipFile` objects. Most users of the :mod:`zipfile` module will not need - to create these, but only use those created by this module. *filename* should be - the full name of the archive member, and *date_time* should be a tuple - containing six fields which describe the time of the last modification to the - file; the fields are described in section :ref:`zipinfo-objects`, "ZipInfo - Objects." + Class used to represent information about a member of an archive. Instances + of this class are returned by the :meth:`getinfo` and :meth:`infolist` + methods of :class:`ZipFile` objects. Most users of the :mod:`zipfile` module + will not need to create these, but only use those created by this + module. *filename* should be the full name of the archive member, and + *date_time* should be a tuple containing six fields which describe the time + of the last modification to the file; the fields are described in section + :ref:`zipinfo-objects`. .. function:: is_zipfile(filename) Modified: doctools/trunk/Doc-26/library/zipimport.rst ============================================================================== --- doctools/trunk/Doc-26/library/zipimport.rst (original) +++ doctools/trunk/Doc-26/library/zipimport.rst Thu Aug 2 16:49:09 2007 @@ -44,8 +44,8 @@ .. class:: zipimporter - The class for importing ZIP files. See "zipimporter Objects" (section - :ref:`zipimporter-objects`) for constructor details. + The class for importing ZIP files. See section :ref:`zipimporter-objects` + for constructor details. .. seealso:: Modified: doctools/trunk/Doc-26/maclib/using.rst ============================================================================== --- doctools/trunk/Doc-26/maclib/using.rst (original) +++ doctools/trunk/Doc-26/maclib/using.rst Thu Aug 2 16:49:09 2007 @@ -108,7 +108,7 @@ /.MacOSX/environment.plist`. See Apple's Technical Document QA1067 for details. For more information on installation Python packages in MacPython, see section -:ref:`mac-package-manager`, "Installing Additional Python Packages." +:ref:`mac-package-manager`. .. _ide: Modified: doctools/trunk/Doc-26/reference/datamodel.rst ============================================================================== --- doctools/trunk/Doc-26/reference/datamodel.rst (original) +++ doctools/trunk/Doc-26/reference/datamodel.rst Thu Aug 2 16:49:09 2007 @@ -442,7 +442,7 @@ the same dictionary entry. Dictionaries are mutable; they can be created by the ``{...}`` notation (see - section :ref:`dict`, "Dictionary Displays"). + section :ref:`dict`). .. index:: module: dbm @@ -462,7 +462,7 @@ pair: function; argument These are the types to which the function call operation (see section - :ref:`calls`, "Calls") can be applied: + :ref:`calls`) can be applied: User-defined functions .. index:: @@ -470,9 +470,9 @@ object: function object: user-defined function - A user-defined function object is created by a function definition (see section - :ref:`function`, "Function definitions"). It should be called with an argument - list containing the same number of items as the function's formal parameter + A user-defined function object is created by a function definition (see + section :ref:`function`). It should be called with an argument list + containing the same number of items as the function's formal parameter list. Special attributes: @@ -649,7 +649,7 @@ single: generator; iterator A function or method which uses the :keyword:`yield` statement (see section - :ref:`yield`, "The :keyword:`yield` statement") is called a :dfn:`generator + :ref:`yield`) is called a :dfn:`generator function`. Such a function, when called, always returns an iterator object which can be used to execute the body of the function: calling the iterator's :meth:`next` method will cause the function to execute until it provides a value @@ -717,7 +717,7 @@ object: module Modules are imported by the :keyword:`import` statement (see section - :ref:`import`, "The :keyword:`import` statement"). A module object has a + :ref:`import`). A module object has a namespace implemented by a dictionary object (this is the dictionary referenced by the func_globals attribute of functions defined in the module). Attribute references are translated to lookups in this dictionary, e.g., ``m.x`` is @@ -750,8 +750,8 @@ of the shared library file. Classes - Class objects are created by class definitions (see section :ref:`class`, "Class - definitions"). A class has a namespace implemented by a dictionary object. Class + Class objects are created by class definitions (see section :ref:`class`). + A class has a namespace implemented by a dictionary object. Class attribute references are translated to lookups in this dictionary, e.g., ``C.x`` is translated to ``C.__dict__["x"]``. When the attribute name is not found there, the attribute search continues in the base classes. The search is depth- @@ -838,8 +838,7 @@ object: mapping Class instances can pretend to be numbers, sequences, or mappings if they have - methods with certain special names. See section :ref:`specialnames`, "Special - method names." + methods with certain special names. See section :ref:`specialnames`. .. index:: single: __dict__ (instance attribute) @@ -1008,7 +1007,7 @@ unwinds the execution stack, at each unwound level a traceback object is inserted in front of the current traceback. When an exception handler is entered, the stack trace is made available to the program. (See section - :ref:`try`, "The ``try`` statement.") It is accessible as ``sys.exc_traceback``, + :ref:`try`.) It is accessible as ``sys.exc_traceback``, and also as the third item of the tuple returned by ``sys.exc_info()``. The latter is the preferred interface, since it works correctly when the program is using multiple threads. When the program contains no suitable handler, the stack Modified: doctools/trunk/Doc-26/reference/expressions.rst ============================================================================== --- doctools/trunk/Doc-26/reference/expressions.rst (original) +++ doctools/trunk/Doc-26/reference/expressions.rst Thu Aug 2 16:49:09 2007 @@ -1253,7 +1253,7 @@ the same box have the same precedence. Unless the syntax is explicitly given, operators are binary. Operators in the same box group left to right (except for comparisons, including tests, which all have the same precedence and chain from -left to right --- see section :ref:`comparisons` -- and exponentiation, which +left to right --- see section :ref:`comparisons` --- and exponentiation, which groups from right to left). +-----------------------------------------------+-------------------------------------+ Modified: doctools/trunk/Doc-26/reference/lexical_analysis.rst ============================================================================== --- doctools/trunk/Doc-26/reference/lexical_analysis.rst (original) +++ doctools/trunk/Doc-26/reference/lexical_analysis.rst Thu Aug 2 16:49:09 2007 @@ -386,8 +386,7 @@ Not imported by ``from module import *``. The special identifier ``_`` is used in the interactive interpreter to store the result of the last evaluation; it is stored in the :mod:`__builtin__` module. When not in interactive mode, ``_`` - has no special meaning and is not defined. See section :ref:`import`, "The - :keyword:`import` statement." + has no special meaning and is not defined. See section :ref:`import`. .. note:: @@ -400,13 +399,13 @@ implementation (including the standard library); applications should not expect to define additional names using this convention. The set of names of this class defined by Python may be extended in future versions. See section - :ref:`specialnames`, "Special method names." + :ref:`specialnames`. ``__*`` Class-private names. Names in this category, when used within the context of a class definition, are re-written to use a mangled form to help avoid name clashes between "private" attributes of base and derived classes. See section - :ref:`atom-identifiers`, "Identifiers (Names)." + :ref:`atom-identifiers`. .. _literals: Modified: doctools/trunk/Doc-26/reference/simple_stmts.rst ============================================================================== --- doctools/trunk/Doc-26/reference/simple_stmts.rst (original) +++ doctools/trunk/Doc-26/reference/simple_stmts.rst Thu Aug 2 16:49:09 2007 @@ -904,7 +904,7 @@ then executed (unless a syntax error occurs). If it is an open file, the file is parsed until EOF and executed. If it is a code object, it is simply executed. In all cases, the code that's executed is expected to be valid as -file input (see section :ref:`file-input`, "File input"). Be aware that the +file input (see section :ref:`file-input`). Be aware that the :keyword:`return` and :keyword:`yield` statements may not be used outside of function definitions even within the context of code passed to the :keyword:`exec` statement. Modified: doctools/trunk/Doc-26/tutorial/errors.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/errors.rst (original) +++ doctools/trunk/Doc-26/tutorial/errors.rst Thu Aug 2 16:49:09 2007 @@ -316,7 +316,7 @@ Many standard modules define their own exceptions to report errors that may occur in functions they define. More information on classes is presented in -chapter :ref:`tut-classes`, "Classes." +chapter :ref:`tut-classes`. .. _tut-cleanup: Modified: doctools/trunk/Doc-26/tutorial/modules.rst ============================================================================== --- doctools/trunk/Doc-26/tutorial/modules.rst (original) +++ doctools/trunk/Doc-26/tutorial/modules.rst Thu Aug 2 16:49:09 2007 @@ -152,16 +152,15 @@ found there, the search continues in an installation-dependent default path; on Unix, this is usually :file:`.:/usr/local/lib/python`. -Actually, modules are searched in the list of directories given by the variable -``sys.path`` which is initialized from the directory containing the input -script (or the current directory), :envvar:`PYTHONPATH` and the installation- -dependent default. This allows Python programs that know what they're doing to -modify or replace the module search path. Note that because the directory -containing the script being run is on the search path, it is important that the -script not have the same name as a standard module, or Python will attempt to -load the script as a module when that module is imported. This will generally be -an error. See section :ref:`tut-standardmodules`, "Standard Modules," for more -information. +Actually, modules are searched in the list of directories given by the variable +``sys.path`` which is initialized from the directory containing the input script +(or the current directory), :envvar:`PYTHONPATH` and the installation- dependent +default. This allows Python programs that know what they're doing to modify or +replace the module search path. Note that because the directory containing the +script being run is on the search path, it is important that the script not have +the same name as a standard module, or Python will attempt to load the script as +a module when that module is imported. This will generally be an error. See +section :ref:`tut-standardmodules` for more information. "Compiled" Python files Modified: doctools/trunk/Doc-3k/c-api/concrete.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/concrete.rst (original) +++ doctools/trunk/Doc-3k/c-api/concrete.rst Thu Aug 2 16:49:09 2007 @@ -1838,9 +1838,8 @@ .. index:: single: PyBufferProcs -More information on the buffer interface is provided in the section "Buffer -Object Structures" (section :ref:`buffer-structs`), under the description for -:ctype:`PyBufferProcs`. +More information on the buffer interface is provided in the section +:ref:`buffer-structs`, under the description for :ctype:`PyBufferProcs`. A "buffer object" is defined in the :file:`bufferobject.h` header (included by :file:`Python.h`). These objects look very similar to string objects at the Modified: doctools/trunk/Doc-3k/c-api/newtypes.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/newtypes.rst (original) +++ doctools/trunk/Doc-3k/c-api/newtypes.rst Thu Aug 2 16:49:09 2007 @@ -701,8 +701,8 @@ .. cmember:: PyBufferProcs* PyTypeObject.tp_as_buffer Pointer to an additional structure that contains fields relevant only to objects - which implement the buffer interface. These fields are documented in "Buffer - Object Structures" (section :ref:`buffer-structs`). + which implement the buffer interface. These fields are documented in + :ref:`buffer-structs`. The :attr:`tp_as_buffer` field is not inherited, but the contained fields are inherited individually. Modified: doctools/trunk/Doc-3k/extending/extending.rst ============================================================================== --- doctools/trunk/Doc-3k/extending/extending.rst (original) +++ doctools/trunk/Doc-3k/extending/extending.rst Thu Aug 2 16:49:09 2007 @@ -453,15 +453,14 @@ } This function must be registered with the interpreter using the -:const:`METH_VARARGS` flag; this is described in section :ref:`methodtable`, -"The Module's Method Table and Initialization Function." The +:const:`METH_VARARGS` flag; this is described in section :ref:`methodtable`. The :cfunc:`PyArg_ParseTuple` function and its arguments are documented in section -:ref:`parsetuple`, "Extracting Parameters in Extension Functions." +:ref:`parsetuple`. The macros :cfunc:`Py_XINCREF` and :cfunc:`Py_XDECREF` increment/decrement the reference count of an object and are safe in the presence of *NULL* pointers (but note that *temp* will not be *NULL* in this context). More info on them -in section :ref:`refcounts`, "Reference Counts." +in section :ref:`refcounts`. .. index:: single: PyEval_CallObject() Modified: doctools/trunk/Doc-3k/install/index.rst ============================================================================== --- doctools/trunk/Doc-3k/install/index.rst (original) +++ doctools/trunk/Doc-3k/install/index.rst Thu Aug 2 16:49:09 2007 @@ -42,7 +42,7 @@ .. % end{latexonly} -.. _intro: +.. _inst-intro: Introduction ============ @@ -67,7 +67,7 @@ the Distributing Python Modules (XXX reference: ../dist/dist.html) manual. -.. _trivial-install: +.. _inst-trivial-install: Best case: trivial installation ------------------------------- @@ -95,7 +95,7 @@ modules from standard source distributions. -.. _new-standard: +.. _inst-new-standard: The new standard: Distutils --------------------------- @@ -119,12 +119,12 @@ get out of this manual. -.. _standard-install: +.. _inst-standard-install: Standard Build and Install ========================== -As described in section :ref:`new-standard`, building and installing a module +As described in section :ref:`inst-new-standard`, building and installing a module distribution using the Distutils is usually one simple command:: python setup.py install @@ -134,7 +134,7 @@ a :command:`Terminal` window to get a shell prompt. -.. _platform-variations: +.. _inst-platform-variations: Platform variations ------------------- @@ -159,7 +159,7 @@ python setup.py install -.. _splitting-up: +.. _inst-splitting-up: Splitting the job up -------------------- @@ -189,7 +189,7 @@ you'll run lots of individual Distutils commands on their own. -.. _how-build-works: +.. _inst-how-build-works: How building works ------------------ @@ -203,7 +203,7 @@ python setup.py build --build-base=/tmp/pybuild/foo-1.0 (Or you could do this permanently with a directive in your system or personal -Distutils configuration file; see section :ref:`config-files`.) Normally, this +Distutils configuration file; see section :ref:`inst-config-files`.) Normally, this isn't necessary. The default layout for the build tree is as follows:: @@ -228,7 +228,7 @@ of installing Python modules and applications. -.. _how-install-works: +.. _inst-how-install-works: How installation works ---------------------- @@ -290,12 +290,12 @@ If you don't want to install modules to the standard location, or if you don't have permission to write there, then you need to read about alternate -installations in section :ref:`alt-install`. If you want to customize your -installation directories more heavily, see section :ref:`custom-install` on +installations in section :ref:`inst-alt-install`. If you want to customize your +installation directories more heavily, see section :ref:`inst-custom-install` on custom installations. -.. _alt-install: +.. _inst-alt-install: Alternate Installation ====================== @@ -317,7 +317,7 @@ you. -.. _alt-install-prefix: +.. _inst-alt-install-prefix: Alternate installation: the home scheme --------------------------------------- @@ -358,7 +358,7 @@ The :option:`--home` option used to be supported only on Unix. -.. _alt-install-home: +.. _inst-alt-install-home: Alternate installation: Unix (the prefix scheme) ------------------------------------------------ @@ -430,7 +430,7 @@ alternate Python installation, this is immaterial.) -.. _alt-install-windows: +.. _inst-alt-install-windows: Alternate installation: Windows (the prefix scheme) --------------------------------------------------- @@ -461,13 +461,13 @@ +------------------------------+---------------------------+-----------------------------+ -.. _custom-install: +.. _inst-custom-install: Custom Installation =================== Sometimes, the alternate installation schemes described in section -:ref:`alt-install` just don't do what you want. You might want to tweak just +:ref:`inst-alt-install` just don't do what you want. You might want to tweak just one or two directories while keeping everything under the same base directory, or you might want to completely redefine the installation scheme. In either case, you're creating a *custom installation scheme*. @@ -513,7 +513,7 @@ The specified installation directories are relative to :file:`{prefix}`. Of course, you also have to ensure that these directories are in Python's module search path, such as by putting a :file:`.pth` file in :file:`{prefix}`. See -section :ref:`search-path` to find out how to modify Python's search path. +section :ref:`inst-search-path` to find out how to modify Python's search path. If you want to define an entire installation scheme, you just have to supply all of the installation directory options. The recommended way to do this is to @@ -548,7 +548,7 @@ Obviously, specifying the entire installation scheme every time you install a new module distribution would be very tedious. Thus, you can put these options -into your Distutils config file (see section :ref:`config-files`):: +into your Distutils config file (see section :ref:`inst-config-files`):: [install] install-base=$HOME @@ -582,7 +582,7 @@ the Distutils additionally define a few extra variables that may not be in your environment, such as ``$PLAT``. (And of course, on systems that don't have environment variables, such as Mac OS 9, the configuration variables supplied by -the Distutils are the only ones you can use.) See section :ref:`config-files` +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 @@ -591,7 +591,7 @@ .. % XXX I'm not sure where this section should go. -.. _search-path: +.. _inst-search-path: Modifying Python's Search Path ------------------------------ @@ -670,7 +670,7 @@ can modify it by adding or removing entries. -.. _config-files: +.. _inst-config-files: Distutils Configuration Files ============================= @@ -685,7 +685,7 @@ by "later" files. -.. _config-filenames: +.. _inst-config-filenames: Location and names of config files ---------------------------------- @@ -748,7 +748,7 @@ Distutils make no attempt to guess your home directory on Windows.) -.. _config-syntax: +.. _inst-config-syntax: Syntax of config files ---------------------- @@ -802,7 +802,7 @@ See also the "Reference" section of the "Distributing Python Modules" manual. -.. _building-ext: +.. _inst-building-ext: Building Extensions: Tips and Tricks ==================================== @@ -815,7 +815,7 @@ to override the usual Distutils behaviour. -.. _tweak-flags: +.. _inst-tweak-flags: Tweaking compiler/linker flags ------------------------------ @@ -885,7 +885,7 @@ the compiler flags specified in the :file:`Setup` file. -.. _non-ms-compilers: +.. _inst-non-ms-compilers: Using non-Microsoft compilers on Windows ---------------------------------------- @@ -932,7 +932,7 @@ If you want to use the Borland C++ compiler as the default, you could specify this in your personal or system-wide configuration file for Distutils (see -section :ref:`config-files`.) +section :ref:`inst-config-files`.) .. seealso:: @@ -998,7 +998,7 @@ If you want to use any of these options/compilers as default, you should consider to write it in your personal or system-wide configuration file for -Distutils (see section :ref:`config-files`.) +Distutils (see section :ref:`inst-config-files`.) .. seealso:: Modified: doctools/trunk/Doc-3k/library/__builtin__.rst ============================================================================== --- doctools/trunk/Doc-3k/library/__builtin__.rst (original) +++ doctools/trunk/Doc-3k/library/__builtin__.rst Thu Aug 2 16:49:09 2007 @@ -8,7 +8,7 @@ This module provides direct access to all 'built-in' identifiers of Python; for example, ``__builtin__.open`` is the full name for the built-in function -:func:`open`. See chapter :ref:`builtin`, "Built-in Objects." +:func:`open`. See chapter :ref:`builtin`. This module is not normally accessed explicitly by most applications, but can be useful in modules that provide objects with the same name as a built-in value, Modified: doctools/trunk/Doc-3k/library/csv.rst ============================================================================== --- doctools/trunk/Doc-3k/library/csv.rst (original) +++ doctools/trunk/Doc-3k/library/csv.rst Thu Aug 2 16:49:09 2007 @@ -72,7 +72,7 @@ :func:`list_dialects` function. The other optional *fmtparam* keyword arguments can be given to override individual formatting parameters in the current dialect. For full details about the dialect and formatting parameters, see - section :ref:`csv-fmt-params`, "Dialects and Formatting Parameters". + section :ref:`csv-fmt-params`. All data read are returned as strings. No automatic data type conversion is performed. @@ -99,7 +99,7 @@ :func:`list_dialects` function. The other optional *fmtparam* keyword arguments can be given to override individual formatting parameters in the current dialect. For full details about the dialect and formatting parameters, see - section :ref:`csv-fmt-params`, "Dialects and Formatting Parameters". To make it + section :ref:`csv-fmt-params`. To make it as easy as possible to interface with modules which implement the DB API, the value :const:`None` is written as the empty string. While this isn't a reversible transformation, it makes it easier to dump SQL NULL data values to @@ -113,8 +113,7 @@ dialect can be specified either by passing a sub-class of :class:`Dialect`, or by *fmtparam* keyword arguments, or both, with keyword arguments overriding parameters of the dialect. For full details about the dialect and formatting - parameters, see section :ref:`csv-fmt-params`, "Dialects and Formatting - Parameters". + parameters, see section :ref:`csv-fmt-params`. .. function:: unregister_dialect(name) Modified: doctools/trunk/Doc-3k/library/ctypes.rst ============================================================================== --- doctools/trunk/Doc-3k/library/ctypes.rst (original) +++ doctools/trunk/Doc-3k/library/ctypes.rst Thu Aug 2 16:49:09 2007 @@ -2359,6 +2359,6 @@ Arrays and pointers ^^^^^^^^^^^^^^^^^^^ -Not yet written - please see section :ref:`ctypes-pointers`, pointers and -section :ref:`ctypes-arrays`, arrays in the tutorial. +Not yet written - please see the sections :ref:`ctypes-pointers` and +section :ref:`ctypes-arrays` in the tutorial. Modified: doctools/trunk/Doc-3k/library/datetime.rst ============================================================================== --- doctools/trunk/Doc-3k/library/datetime.rst (original) +++ doctools/trunk/Doc-3k/library/datetime.rst Thu Aug 2 16:49:09 2007 @@ -491,7 +491,7 @@ Return a string representing the date, controlled by an explicit format string. Format codes referring to hours, minutes or seconds will see 0 values. See - section :ref:`strftime-behavior` -- :meth:`strftime` behavior. + section :ref:`strftime-behavior`. .. _datetime-datetime: @@ -931,7 +931,7 @@ .. method:: datetime.strftime(format) Return a string representing the date and time, controlled by an explicit format - string. See section :ref:`strftime-behavior` -- :meth:`strftime` behavior. + string. See section :ref:`strftime-behavior`. .. _datetime-time: @@ -1056,7 +1056,7 @@ .. method:: time.strftime(format) Return a string representing the time, controlled by an explicit format string. - See section :ref:`strftime-behavior` -- :meth:`strftime` behavior. + See section :ref:`strftime-behavior`. .. method:: time.utcoffset() Modified: doctools/trunk/Doc-3k/library/functions.rst ============================================================================== --- doctools/trunk/Doc-3k/library/functions.rst (original) +++ doctools/trunk/Doc-3k/library/functions.rst Thu Aug 2 16:49:09 2007 @@ -451,10 +451,9 @@ .. function:: file(filename[, mode[, bufsize]]) - Constructor function for the :class:`file` type, described further in section - :ref:`bltin-file-objects`, "File Objects (XXX reference: bltin-file- - objects.html)". The constructor's arguments are the same as those of the - :func:`open` built-in function described below. + Constructor function for the :class:`file` type, described further in section + :ref:`bltin-file-objects`. The constructor's arguments are the same as those + of the :func:`open` built-in function described below. When opening a file, it's preferable to use :func:`open` instead of invoking this constructor directly. :class:`file` is more suited to type testing (for @@ -743,11 +742,10 @@ .. function:: open(filename[, mode[, bufsize]]) - Open a file, returning an object of the :class:`file` type described in section - :ref:`bltin-file-objects`, "File Objects (XXX reference: bltin-file- - objects.html)". If the file cannot be opened, :exc:`IOError` is raised. When - opening a file, it's preferable to use :func:`open` instead of invoking the - :class:`file` constructor directly. + Open a file, returning an object of the :class:`file` type described in + section :ref:`bltin-file-objects`. If the file cannot be opened, + :exc:`IOError` is raised. When opening a file, it's preferable to use + :func:`open` instead of invoking the :class:`file` constructor directly. The first two arguments are the same as for ``stdio``'s :cfunc:`fopen`: *filename* is the file name to be opened, and *mode* is a string indicating how Modified: doctools/trunk/Doc-3k/library/intro.rst ============================================================================== --- doctools/trunk/Doc-3k/library/intro.rst (original) +++ doctools/trunk/Doc-3k/library/intro.rst Thu Aug 2 16:49:09 2007 @@ -44,9 +44,8 @@ function, module or term in the index (in the back). And finally, if you enjoy learning about random subjects, you choose a random page number (see module :mod:`random`) and read a section or two. Regardless of the order in which you -read the sections of this manual, it helps to start with chapter -:ref:`builtin`, "Built-in Types, Exceptions and Functions," as the remainder of -the manual assumes familiarity with this material. +read the sections of this manual, it helps to start with chapter :ref:`builtin`, +as the remainder of the manual assumes familiarity with this material. Let the show begin! Modified: doctools/trunk/Doc-3k/library/logging.rst ============================================================================== --- doctools/trunk/Doc-3k/library/logging.rst (original) +++ doctools/trunk/Doc-3k/library/logging.rst Thu Aug 2 16:49:09 2007 @@ -1483,8 +1483,8 @@ of the :class:`LogRecord` attributes - such as the default value mentioned above making use of the fact that the user's message and arguments are pre-formatted into a :class:`LogRecord`'s *message* attribute. This format string contains -standard python %-style mapping keys. See section :ref:`typesseq-strings`, -"String Formatting Operations," for more information on string formatting. +standard python %-style mapping keys. See section :ref:`typesseq-strings` +for more information on string formatting. Currently, the useful mapping keys in a :class:`LogRecord` are: Modified: doctools/trunk/Doc-3k/library/optparse.rst ============================================================================== --- doctools/trunk/Doc-3k/library/optparse.rst (original) +++ doctools/trunk/Doc-3k/library/optparse.rst Thu Aug 2 16:49:09 2007 @@ -309,7 +309,7 @@ Actions tell :mod:`optparse` what to do when it encounters an option on the command line. There is a fixed set of actions hard-coded into :mod:`optparse`; adding new actions is an advanced topic covered in section -:ref:`optparse-extending-optparse`, Extending :mod:`optparse`. Most actions tell +:ref:`optparse-extending-optparse`. Most actions tell :mod:`optparse` to store a value in some variable---for example, take a string from the command line and store it in an attribute of ``options``. @@ -369,8 +369,7 @@ default destination for ``"-f"`` is ``f``. :mod:`optparse` also includes built-in ``long`` and ``complex`` types. Adding -types is covered in section :ref:`optparse-extending-optparse`, Extending -:mod:`optparse`. +types is covered in section :ref:`optparse-extending-optparse`. .. _optparse-handling-boolean-options: @@ -415,7 +414,7 @@ call a specified function These are covered in section :ref:`optparse-reference-guide`, Reference Guide -and section :ref:`optparse-option-callbacks`, Option Callbacks. +and section :ref:`optparse-option-callbacks`. .. _optparse-default-values: @@ -704,8 +703,7 @@ ``conflict_handler`` (default: ``"error"``) Specifies what to do when options with conflicting option strings are added to - the parser; see section :ref:`optparse-conflicts-between-options`, Conflicts - between options. + the parser; see section :ref:`optparse-conflicts-between-options`. ``description`` (default: ``None``) A paragraph of text giving a brief overview of your program. :mod:`optparse` @@ -734,8 +732,7 @@ There are several ways to populate the parser with options. The preferred way is by using ``OptionParser.add_option()``, as shown in section -:ref:`optparse-tutorial`, the tutorial. :meth:`add_option` can be called in one -of two ways: +:ref:`optparse-tutorial`. :meth:`add_option` can be called in one of two ways: * pass it an Option instance (as returned by :func:`make_option`) @@ -986,7 +983,7 @@ func(option, opt_str, value, parser, *args, **kwargs) - See section :ref:`optparse-option-callbacks`, Option Callbacks for more detail. + See section :ref:`optparse-option-callbacks` for more detail. * :attr:`help` @@ -1083,9 +1080,9 @@ * ``callback`` - For options with action ``"callback"``, the callable to call when this option is - seen. See section :ref:`optparse-option-callbacks`, Option Callbacks for detail - on the arguments passed to ``callable``. + For options with action ``"callback"``, the callable to call when this option + is seen. See section :ref:`optparse-option-callbacks` for detail on the + arguments passed to ``callable``. * ``callback_args``, ``callback_kwargs`` @@ -1102,7 +1099,7 @@ * ``metavar`` (default: derived from option strings) Stand-in for the option argument(s) to use when printing help text. See section - :ref:`optparse-tutorial`, the tutorial for an example. + :ref:`optparse-tutorial` for an example. .. _optparse-standard-option-types: @@ -1112,7 +1109,7 @@ :mod:`optparse` has six built-in option types: ``string``, ``int``, ``long``, ``choice``, ``float`` and ``complex``. If you need to add new option types, see -section :ref:`optparse-extending-optparse`, Extending :mod:`optparse`. +section :ref:`optparse-extending-optparse`. Arguments to string options are not checked or converted in any way: the text on the command line is stored in the destination (or passed to the callback) as-is. Modified: doctools/trunk/Doc-3k/library/os.rst ============================================================================== --- doctools/trunk/Doc-3k/library/os.rst (original) +++ doctools/trunk/Doc-3k/library/os.rst Thu Aug 2 16:49:09 2007 @@ -122,8 +122,7 @@ getcwd() :noindex: - These functions are described in "Files and Directories" (section - :ref:`os-file-dir`). + These functions are described in :ref:`os-file-dir`. .. function:: ctermid() Modified: doctools/trunk/Doc-3k/library/pyexpat.rst ============================================================================== --- doctools/trunk/Doc-3k/library/pyexpat.rst (original) +++ doctools/trunk/Doc-3k/library/pyexpat.rst Thu Aug 2 16:49:09 2007 @@ -39,8 +39,7 @@ .. exception:: ExpatError The exception raised when Expat reports an error. See section - :ref:`expaterror-objects`, "ExpatError Exceptions," for more information on - interpreting Expat errors. + :ref:`expaterror-objects` for more information on interpreting Expat errors. .. exception:: error Modified: doctools/trunk/Doc-3k/library/shlex.rst ============================================================================== --- doctools/trunk/Doc-3k/library/shlex.rst (original) +++ doctools/trunk/Doc-3k/library/shlex.rst Thu Aug 2 16:49:09 2007 @@ -58,7 +58,7 @@ was introduced in Python 2.3, and defines the operational mode. When *posix* is not true (default), the :class:`shlex` instance will operate in compatibility mode. When operating in POSIX mode, :class:`shlex` will try to be as close as - possible to the POSIX shell parsing rules. See section :ref:`shlex-objects`. + possible to the POSIX shell parsing rules. .. seealso:: Modified: doctools/trunk/Doc-3k/library/socket.rst ============================================================================== --- doctools/trunk/Doc-3k/library/socket.rst (original) +++ doctools/trunk/Doc-3k/library/socket.rst Thu Aug 2 16:49:09 2007 @@ -571,13 +571,12 @@ .. index:: single: I/O control; buffering Return a :dfn:`file object` associated with the socket. (File objects are - described in :ref:`bltin-file-objects`, "File Objects.") The file object + described in :ref:`bltin-file-objects`.) The file object references a :cfunc:`dup`\ ped version of the socket file descriptor, so the 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 "Built-in Functions" (section :ref:`built-in-funcs`) - for more information. + :func:`file` function; see :ref:`built-in-funcs` for more information. .. method:: socket.recv(bufsize[, flags]) Modified: doctools/trunk/Doc-3k/library/sqlite3.rst ============================================================================== --- doctools/trunk/Doc-3k/library/sqlite3.rst (original) +++ doctools/trunk/Doc-3k/library/sqlite3.rst Thu Aug 2 16:49:09 2007 @@ -227,8 +227,8 @@ .. attribute:: Connection.isolation_level Get or set the current isolation level. None for autocommit mode or one of - "DEFERRED", "IMMEDIATE" or "EXLUSIVE". See "Controlling Transactions", section - :ref:`sqlite3-controlling-transactions`, for a more detailed explanation. + "DEFERRED", "IMMEDIATE" or "EXLUSIVE". See section + :ref:`sqlite3-controlling-transactions` for a more detailed explanation. .. method:: Connection.cursor([cursorClass]) @@ -629,9 +629,8 @@ * Explicitly via the column name -Both ways are described in "Module Constants", section -:ref:`sqlite3-module-contents`, in the entries for the constants -:const:`PARSE_DECLTYPES` and :const:`PARSE_COLNAMES`. +Both ways are described in section :ref:`sqlite3-module-contents`, in the entries +for the constants :const:`PARSE_DECLTYPES` and :const:`PARSE_COLNAMES`. The following example illustrates both approaches. Modified: doctools/trunk/Doc-3k/library/stdtypes.rst ============================================================================== --- doctools/trunk/Doc-3k/library/stdtypes.rst (original) +++ doctools/trunk/Doc-3k/library/stdtypes.rst Thu Aug 2 16:49:09 2007 @@ -333,7 +333,7 @@ for well-defined conversions. (3) - See section :ref:`built-in-funcs`, "Built-in Functions," for a full description. + See :ref:`built-in-funcs` for a full description. (4) Complex floor division operator, modulo operator, and :func:`divmod`. @@ -1722,9 +1722,9 @@ File objects are implemented using C's ``stdio`` package and can be created with the built-in constructor :func:`file` described in section -:ref:`built-in-funcs`, "Built-in Functions." [#]_ 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 objects. +:ref:`built-in-funcs`. [#]_ 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 objects. When a file operation fails for an I/O-related reason, the exception :exc:`IOError` is raised. This includes situations where the operation is not @@ -2339,4 +2339,3 @@ might matter, for example, if you want to make an exact copy of a file while scanning its lines) to tell whether the last line of a file ended in a newline or not (yes this happens!). - Modified: doctools/trunk/Doc-3k/library/string.rst ============================================================================== --- doctools/trunk/Doc-3k/library/string.rst (original) +++ doctools/trunk/Doc-3k/library/string.rst Thu Aug 2 16:49:09 2007 @@ -245,10 +245,9 @@ --------------------------- The following list of functions are also defined as methods of string and -Unicode objects; see "String Methods" (section :ref:`string-methods`) for more -information on those. You should consider these functions as deprecated, -although they will not be removed until Python 3.0. The functions defined in -this module are: +Unicode objects; see section :ref:`string-methods` for more information on +those. You should consider these functions as deprecated, although they will +not be removed until Python 3.0. The functions defined in this module are: .. function:: atof(s) Modified: doctools/trunk/Doc-3k/library/sys.rst ============================================================================== --- doctools/trunk/Doc-3k/library/sys.rst (original) +++ doctools/trunk/Doc-3k/library/sys.rst Thu Aug 2 16:49:09 2007 @@ -331,7 +331,7 @@ Their intended use is to allow an interactive user to import a debugger module and engage in post-mortem debugging without having to re-execute the command that caused the error. (Typical use is ``import pdb; pdb.pm()`` to enter the - post-mortem debugger; see chapter :ref:`debugger`, "The Python Debugger," for + post-mortem debugger; see chapter :ref:`debugger` for more information.) The meaning of the variables is the same as that of the return values from @@ -490,9 +490,9 @@ single: trace function single: debugger - Set the system's trace function, which allows you to implement a Python source - code debugger in Python. See section :ref:`debugger-hooks`, "How It Works," in - the chapter on the Python debugger. The function is thread-specific; for a + Set the system's trace function, which allows you to implement a Python + source code debugger in Python. See section :ref:`debugger-hooks` in the + chapter on the Python debugger. The function is thread-specific; for a debugger to support multiple threads, it must be registered using :func:`settrace` for each thread being debugged. Modified: doctools/trunk/Doc-3k/library/tarfile.rst ============================================================================== --- doctools/trunk/Doc-3k/library/tarfile.rst (original) +++ doctools/trunk/Doc-3k/library/tarfile.rst Thu Aug 2 16:49:09 2007 @@ -37,7 +37,7 @@ Return a :class:`TarFile` object for the pathname *name*. For detailed information on :class:`TarFile` objects and the keyword arguments that are - allowed, see TarFile Objects (section :ref:`tarfile-objects`). + allowed, see :ref:`tarfile-objects`. *mode* has to be a string of the form ``'filemode[:compression]'``, it defaults to ``'r'``. Here is a full list of mode combinations: @@ -75,14 +75,14 @@ For special purposes, there is a second format for *mode*: ``'filemode|[compression]'``. :func:`open` will return a :class:`TarFile` - object that processes its data as a stream of blocks. No random seeking will be - done on the file. If given, *fileobj* may be any object that has a :meth:`read` - or :meth:`write` method (depending on the *mode*). *bufsize* specifies the - blocksize and defaults to ``20 * 512`` bytes. Use this variant in combination - with e.g. ``sys.stdin``, a socket file object or a tape device. However, such a - :class:`TarFile` object is limited in that it does not allow to be accessed - randomly, see "Examples" (section :ref:`tar-examples`). The currently possible - modes: + object that processes its data as a stream of blocks. No random seeking will + be done on the file. If given, *fileobj* may be any object that has a + :meth:`read` or :meth:`write` method (depending on the *mode*). *bufsize* + specifies the blocksize and defaults to ``20 * 512`` bytes. Use this variant + in combination with e.g. ``sys.stdin``, a socket file object or a tape + device. However, such a :class:`TarFile` object is limited in that it does + not allow to be accessed randomly, see :ref:`tar-examples`. The currently + possible modes: +-------------+--------------------------------------------+ | Mode | Action | @@ -112,8 +112,7 @@ .. class:: TarFile Class for reading and writing tar archives. Do not use this class directly, - better use :func:`open` instead. See "TarFile Objects" (section - :ref:`tarfile-objects`). + better use :func:`open` instead. See :ref:`tarfile-objects`. .. function:: is_tarfile(name) @@ -221,7 +220,7 @@ archive is a sequence of blocks. An archive member (a stored file) is made up of a header block followed by data blocks. It is possible to store a file in a tar archive several times. Each archive member is represented by a :class:`TarInfo` -object, see TarInfo Objects (section :ref:`tarinfo-objects`) for details. +object, see :ref:`tarinfo-objects` for details. .. class:: TarFile(name=None, mode='r', fileobj=None, format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False, ignore_zeros=False, encoding=None, errors=None, pax_headers=None, debug=0, errorlevel=0) Modified: doctools/trunk/Doc-3k/library/tkinter.rst ============================================================================== --- doctools/trunk/Doc-3k/library/tkinter.rst (original) +++ doctools/trunk/Doc-3k/library/tkinter.rst Thu Aug 2 16:49:09 2007 @@ -22,9 +22,8 @@ classes. In addition, the internal module :mod:`_tkinter` provides a threadsafe mechanism which allows Python and Tcl to interact. -Tk is not the only GUI for Python; see section :ref:`other-gui-packages`, "Other -User Interface Modules and Packages," for more information on other GUI toolkits -for Python. +Tk is not the only GUI for Python; see section :ref:`other-gui-packages` for +more information on other GUI toolkits for Python. .. % Other sections I have in mind are .. % Tkinter internals Modified: doctools/trunk/Doc-3k/library/urlparse.rst ============================================================================== --- doctools/trunk/Doc-3k/library/urlparse.rst (original) +++ doctools/trunk/Doc-3k/library/urlparse.rst Thu Aug 2 16:49:09 2007 @@ -90,8 +90,8 @@ | | | if present | | +------------------+-------+--------------------------+----------------------+ - See section :ref:`urlparse-result-object`, "Results of :func:`urlparse` and - :func:`urlsplit`," for more information on the result object. + See section :ref:`urlparse-result-object` for more information on the result + object. .. versionchanged:: 2.5 Added attributes to return value. @@ -141,8 +141,8 @@ | | | if present | | +------------------+-------+-------------------------+----------------------+ - See section :ref:`urlparse-result-object`, "Results of :func:`urlparse` and - :func:`urlsplit`," for more information on the result object. + See section :ref:`urlparse-result-object` for more information on the result + object. .. versionadded:: 2.2 Modified: doctools/trunk/Doc-3k/library/userdict.rst ============================================================================== --- doctools/trunk/Doc-3k/library/userdict.rst (original) +++ doctools/trunk/Doc-3k/library/userdict.rst Thu Aug 2 16:49:09 2007 @@ -177,8 +177,8 @@ hard to track down. In addition to supporting the methods and operations of string and Unicode -objects (see section :ref:`string-methods`, "String Methods"), -:class:`UserString` instances provide the following attribute: +objects (see section :ref:`string-methods`), :class:`UserString` instances +provide the following attribute: .. attribute:: MutableString.data Modified: doctools/trunk/Doc-3k/library/xml.dom.rst ============================================================================== --- doctools/trunk/Doc-3k/library/xml.dom.rst (original) +++ doctools/trunk/Doc-3k/library/xml.dom.rst Thu Aug 2 16:49:09 2007 @@ -65,8 +65,7 @@ and OMG IDL. The Python mapping defined here is based in large part on the IDL version of the specification, but strict compliance is not required (though implementations are free to support the strict mapping from IDL). See section -:ref:`dom-conformance`, "Conformance," for a detailed discussion of mapping -requirements. +:ref:`dom-conformance` for a detailed discussion of mapping requirements. .. seealso:: @@ -173,40 +172,40 @@ strings. It is fairly rare that you must do this, however, so this usage is not yet documented. -+--------------------------------+---------------------------------+---------------------------------+ -| Interface | Section | Purpose | -+================================+=================================+=================================+ -| :class:`DOMImplementation` | :ref:`dom-implementation- | Interface to the underlying | -| | objects` | implementation. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`Node` | :ref:`dom-node-objects` | Base interface for most objects | -| | | in a document. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`NodeList` | :ref:`dom-nodelist-objects` | Interface for a sequence of | -| | | nodes. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`DocumentType` | :ref:`dom-documenttype-objects` | Information about the | -| | | declarations needed to process | -| | | a document. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`Document` | :ref:`dom-document-objects` | Object which represents an | -| | | entire document. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`Element` | :ref:`dom-element-objects` | Element nodes in the document | -| | | hierarchy. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`Attr` | :ref:`dom-attr-objects` | Attribute value nodes on | -| | | element nodes. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`Comment` | :ref:`dom-comment-objects` | Representation of comments in | -| | | the source document. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`Text` | :ref:`dom-text-objects` | Nodes containing textual | -| | | content from the document. | -+--------------------------------+---------------------------------+---------------------------------+ -| :class:`ProcessingInstruction` | :ref:`dom-pi-objects` | Processing instruction | -| | | representation. | -+--------------------------------+---------------------------------+---------------------------------+ ++--------------------------------+-----------------------------------+---------------------------------+ +| Interface | Section | Purpose | ++================================+===================================+=================================+ +| :class:`DOMImplementation` | :ref:`dom-implementation-objects` | Interface to the underlying | +| | | implementation. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`Node` | :ref:`dom-node-objects` | Base interface for most objects | +| | | in a document. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`NodeList` | :ref:`dom-nodelist-objects` | Interface for a sequence of | +| | | nodes. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`DocumentType` | :ref:`dom-documenttype-objects` | Information about the | +| | | declarations needed to process | +| | | a document. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`Document` | :ref:`dom-document-objects` | Object which represents an | +| | | entire document. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`Element` | :ref:`dom-element-objects` | Element nodes in the document | +| | | hierarchy. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`Attr` | :ref:`dom-attr-objects` | Attribute value nodes on | +| | | element nodes. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`Comment` | :ref:`dom-comment-objects` | Representation of comments in | +| | | the source document. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`Text` | :ref:`dom-text-objects` | Nodes containing textual | +| | | content from the document. | ++--------------------------------+-----------------------------------+---------------------------------+ +| :class:`ProcessingInstruction` | :ref:`dom-pi-objects` | Processing instruction | +| | | representation. | ++--------------------------------+-----------------------------------+---------------------------------+ An additional section describes the exceptions defined for working with the DOM in Python. Modified: doctools/trunk/Doc-3k/library/xml.sax.reader.rst ============================================================================== --- doctools/trunk/Doc-3k/library/xml.sax.reader.rst (original) +++ doctools/trunk/Doc-3k/library/xml.sax.reader.rst Thu Aug 2 16:49:09 2007 @@ -70,24 +70,23 @@ .. class:: AttributesImpl(attrs) - This is an implementation of the :class:`Attributes` interface (XXX reference: - attributes-objects.html) (see section :ref:`attributes-objects`). This is a - dictionary-like object which represents the element attributes in a - :meth:`startElement` call. In addition to the most useful dictionary operations, - it supports a number of other methods as described by the interface. Objects of - this class should be instantiated by readers; *attrs* must be a dictionary-like - object containing a mapping from attribute names to attribute values. + This is an implementation of the :class:`Attributes` interface (see section + :ref:`attributes-objects`). This is a dictionary-like object which + represents the element attributes in a :meth:`startElement` call. In addition + to the most useful dictionary operations, it supports a number of other + methods as described by the interface. Objects of this class should be + instantiated by readers; *attrs* must be a dictionary-like object containing + a mapping from attribute names to attribute values. .. class:: AttributesNSImpl(attrs, qnames) Namespace-aware variant of :class:`AttributesImpl`, which will be passed to :meth:`startElementNS`. It is derived from :class:`AttributesImpl`, but - understands attribute names as two-tuples of *namespaceURI* and *localname*. In - addition, it provides a number of methods expecting qualified names as they - appear in the original document. This class implements the - :class:`AttributesNS` interface (XXX reference: attributes-ns-objects.html) (see - section :ref:`attributes-ns-objects`). + understands attribute names as two-tuples of *namespaceURI* and + *localname*. In addition, it provides a number of methods expecting qualified + names as they appear in the original document. This class implements the + :class:`AttributesNS` interface (see section :ref:`attributes-ns-objects`). .. _xmlreader-objects: @@ -359,9 +358,9 @@ The :class:`AttributesNS` Interface ----------------------------------- -This interface is a subtype of the :class:`Attributes` interface (XXX reference: -attributes-objects.html) (see section :ref:`attributes-objects`). All methods -supported by that interface are also available on :class:`AttributesNS` objects. +This interface is a subtype of the :class:`Attributes` interface (see section +:ref:`attributes-objects`). All methods supported by that interface are also +available on :class:`AttributesNS` objects. The following methods are also available: Modified: doctools/trunk/Doc-3k/library/zipfile.rst ============================================================================== --- doctools/trunk/Doc-3k/library/zipfile.rst (original) +++ doctools/trunk/Doc-3k/library/zipfile.rst Thu Aug 2 16:49:09 2007 @@ -40,8 +40,8 @@ .. class:: ZipFile - The class for reading and writing ZIP files. See "ZipFile Objects" (section - :ref:`zipfile-objects`) for constructor details. + The class for reading and writing ZIP files. See section + :ref:`zipfile-objects` for constructor details. .. class:: PyZipFile @@ -51,14 +51,14 @@ .. class:: ZipInfo([filename[, date_time]]) - Class used to represent information about a member of an archive. Instances of - this class are returned by the :meth:`getinfo` and :meth:`infolist` methods of - :class:`ZipFile` objects. Most users of the :mod:`zipfile` module will not need - to create these, but only use those created by this module. *filename* should be - the full name of the archive member, and *date_time* should be a tuple - containing six fields which describe the time of the last modification to the - file; the fields are described in section :ref:`zipinfo-objects`, "ZipInfo - Objects." + Class used to represent information about a member of an archive. Instances + of this class are returned by the :meth:`getinfo` and :meth:`infolist` + methods of :class:`ZipFile` objects. Most users of the :mod:`zipfile` module + will not need to create these, but only use those created by this + module. *filename* should be the full name of the archive member, and + *date_time* should be a tuple containing six fields which describe the time + of the last modification to the file; the fields are described in section + :ref:`zipinfo-objects`. .. function:: is_zipfile(filename) Modified: doctools/trunk/Doc-3k/library/zipimport.rst ============================================================================== --- doctools/trunk/Doc-3k/library/zipimport.rst (original) +++ doctools/trunk/Doc-3k/library/zipimport.rst Thu Aug 2 16:49:09 2007 @@ -40,8 +40,8 @@ .. class:: zipimporter - The class for importing ZIP files. See "zipimporter Objects" (section - :ref:`zipimporter-objects`) for constructor details. + The class for importing ZIP files. See section :ref:`zipimporter-objects` + for constructor details. .. seealso:: Modified: doctools/trunk/Doc-3k/maclib/using.rst ============================================================================== --- doctools/trunk/Doc-3k/maclib/using.rst (original) +++ doctools/trunk/Doc-3k/maclib/using.rst Thu Aug 2 16:49:09 2007 @@ -108,7 +108,7 @@ /.MacOSX/environment.plist`. See Apple's Technical Document QA1067 for details. For more information on installation Python packages in MacPython, see section -:ref:`mac-package-manager`, "Installing Additional Python Packages." +:ref:`mac-package-manager`. .. _ide: Modified: doctools/trunk/Doc-3k/reference/datamodel.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/datamodel.rst (original) +++ doctools/trunk/Doc-3k/reference/datamodel.rst Thu Aug 2 16:49:09 2007 @@ -441,7 +441,7 @@ the same dictionary entry. Dictionaries are mutable; they can be created by the ``{...}`` notation (see - section :ref:`dict`, "Dictionary Displays"). + section :ref:`dict`). .. index:: module: dbm @@ -461,7 +461,7 @@ pair: function; argument These are the types to which the function call operation (see section - :ref:`calls`, "Calls") can be applied: + :ref:`calls`) can be applied: User-defined functions .. index:: @@ -469,9 +469,9 @@ object: function object: user-defined function - A user-defined function object is created by a function definition (see section - :ref:`function`, "Function definitions"). It should be called with an argument - list containing the same number of items as the function's formal parameter + A user-defined function object is created by a function definition (see + section :ref:`function`). It should be called with an argument list + containing the same number of items as the function's formal parameter list. Special attributes: @@ -652,7 +652,7 @@ single: generator; iterator A function or method which uses the :keyword:`yield` statement (see section - :ref:`yield`, "The :keyword:`yield` statement") is called a :dfn:`generator + :ref:`yield`) is called a :dfn:`generator function`. Such a function, when called, always returns an iterator object which can be used to execute the body of the function: calling the iterator's :meth:`__next__` method will cause the function to execute until it provides a @@ -720,7 +720,7 @@ object: module Modules are imported by the :keyword:`import` statement (see section - :ref:`import`, "The :keyword:`import` statement"). A module object has a + :ref:`import`). A module object has a namespace implemented by a dictionary object (this is the dictionary referenced by the __globals__ attribute of functions defined in the module). Attribute references are translated to lookups in this dictionary, e.g., ``m.x`` is @@ -753,8 +753,8 @@ of the shared library file. Classes - Class objects are created by class definitions (see section :ref:`class`, "Class - definitions"). A class has a namespace implemented by a dictionary object. Class + Class objects are created by class definitions (see section :ref:`class`). + A class has a namespace implemented by a dictionary object. Class attribute references are translated to lookups in this dictionary, e.g., ``C.x`` is translated to ``C.__dict__["x"]``. When the attribute name is not found there, the attribute search continues in the base classes. The search is depth- @@ -841,8 +841,7 @@ object: mapping Class instances can pretend to be numbers, sequences, or mappings if they have - methods with certain special names. See section :ref:`specialnames`, "Special - method names." + methods with certain special names. See section :ref:`specialnames`. .. index:: single: __dict__ (instance attribute) @@ -1008,7 +1007,7 @@ unwinds the execution stack, at each unwound level a traceback object is inserted in front of the current traceback. When an exception handler is entered, the stack trace is made available to the program. (See section - :ref:`try`, "The ``try`` statement.") It is accessible as the third item of the + :ref:`try`.) It is accessible as the third item of the tuple returned by ``sys.exc_info()``. When the program contains no suitable handler, the stack trace is written (nicely formatted) to the standard error stream; if the interpreter is interactive, it is also made available to the user Modified: doctools/trunk/Doc-3k/reference/expressions.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/expressions.rst (original) +++ doctools/trunk/Doc-3k/reference/expressions.rst Thu Aug 2 16:49:09 2007 @@ -1199,7 +1199,7 @@ the same box have the same precedence. Unless the syntax is explicitly given, operators are binary. Operators in the same box group left to right (except for comparisons, including tests, which all have the same precedence and chain from -left to right --- see section :ref:`comparisons` -- and exponentiation, which +left to right --- see section :ref:`comparisons` --- and exponentiation, which groups from right to left). +----------------------------------------------+-------------------------------------+ Modified: doctools/trunk/Doc-3k/reference/lexical_analysis.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/lexical_analysis.rst (original) +++ doctools/trunk/Doc-3k/reference/lexical_analysis.rst Thu Aug 2 16:49:09 2007 @@ -385,8 +385,7 @@ Not imported by ``from module import *``. The special identifier ``_`` is used in the interactive interpreter to store the result of the last evaluation; it is stored in the :mod:`__builtin__` module. When not in interactive mode, ``_`` - has no special meaning and is not defined. See section :ref:`import`, "The - :keyword:`import` statement." + has no special meaning and is not defined. See section :ref:`import`. .. note:: @@ -399,13 +398,13 @@ implementation (including the standard library); applications should not expect to define additional names using this convention. The set of names of this class defined by Python may be extended in future versions. See section - :ref:`specialnames`, "Special method names." + :ref:`specialnames`. ``__*`` Class-private names. Names in this category, when used within the context of a class definition, are re-written to use a mangled form to help avoid name clashes between "private" attributes of base and derived classes. See section - :ref:`atom-identifiers`, "Identifiers (Names)." + :ref:`atom-identifiers`. .. _literals: Modified: doctools/trunk/Doc-3k/tutorial/errors.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/errors.rst (original) +++ doctools/trunk/Doc-3k/tutorial/errors.rst Thu Aug 2 16:49:09 2007 @@ -323,7 +323,7 @@ Many standard modules define their own exceptions to report errors that may occur in functions they define. More information on classes is presented in -chapter :ref:`tut-classes`, "Classes." +chapter :ref:`tut-classes`. .. _tut-cleanup: Modified: doctools/trunk/Doc-3k/tutorial/modules.rst ============================================================================== --- doctools/trunk/Doc-3k/tutorial/modules.rst (original) +++ doctools/trunk/Doc-3k/tutorial/modules.rst Thu Aug 2 16:49:09 2007 @@ -152,16 +152,15 @@ found there, the search continues in an installation-dependent default path; on Unix, this is usually :file:`.:/usr/local/lib/python`. -Actually, modules are searched in the list of directories given by the variable -``sys.path`` which is initialized from the directory containing the input -script (or the current directory), :envvar:`PYTHONPATH` and the installation- -dependent default. This allows Python programs that know what they're doing to -modify or replace the module search path. Note that because the directory -containing the script being run is on the search path, it is important that the -script not have the same name as a standard module, or Python will attempt to -load the script as a module when that module is imported. This will generally be -an error. See section :ref:`tut-standardmodules`, "Standard Modules," for more -information. +Actually, modules are searched in the list of directories given by the variable +``sys.path`` which is initialized from the directory containing the input script +(or the current directory), :envvar:`PYTHONPATH` and the installation- dependent +default. This allows Python programs that know what they're doing to modify or +replace the module search path. Note that because the directory containing the +script being run is on the search path, it is important that the script not have +the same name as a standard module, or Python will attempt to load the script as +a module when that module is imported. This will generally be an error. See +section :ref:`tut-standardmodules` for more information. "Compiled" Python files

1 0

r56668 - doctools/trunk/Doc-3k/library/email-examples.rst
by georg.brandl Aug. 2, 2007

Aug. 2, 2007

Author: georg.brandl Date: Thu Aug 2 15:08:35 2007 New Revision: 56668 Added: doctools/trunk/Doc-3k/library/email-examples.rst Log: Forgot to add new merged file. Added: doctools/trunk/Doc-3k/library/email-examples.rst ============================================================================== --- (empty file) +++ doctools/trunk/Doc-3k/library/email-examples.rst Thu Aug 2 15:08:35 2007 @@ -0,0 +1,38 @@ +:mod:`email`: Examples +---------------------- + +Here are a few examples of how to use the :mod:`email` package to read, write, +and send simple email messages, as well as more complex MIME messages. + +First, let's see how to create and send a simple text message: + + +.. include:: ../includes/email-simple.py + :literal: + +Here's an example of how to send a MIME message containing a bunch of family +pictures that may be residing in a directory: + + +.. include:: ../includes/email-mime.py + :literal: + +Here's an example of how to send the entire contents of a directory as an email +message: [#]_ + + +.. include:: ../includes/email-dir.py + :literal: + +And finally, here's an example of how to unpack a MIME message like the one +above, into a directory of files: + + +.. include:: ../includes/email-unpack.py + :literal: + + +.. rubric:: Footnotes + +.. [#] Thanks to Matthew Dixon Cowles for the original inspiration and examples. +

1 0

Aug. 2, 2007

Author: georg.brandl Date: Thu Aug 2 15:06:23 2007 New Revision: 56667 Modified: doctools/trunk/Doc-26/TODO doctools/trunk/Doc-26/bugs.rst doctools/trunk/Doc-26/c-api/concrete.rst doctools/trunk/Doc-26/c-api/init.rst doctools/trunk/Doc-26/c-api/utilities.rst doctools/trunk/Doc-26/extending/windows.rst doctools/trunk/Doc-26/library/curses.rst doctools/trunk/Doc-26/library/decimal.rst doctools/trunk/Doc-26/library/dis.rst doctools/trunk/Doc-26/library/filesys.rst doctools/trunk/Doc-26/library/gl.rst doctools/trunk/Doc-26/library/operator.rst doctools/trunk/Doc-26/library/optparse.rst doctools/trunk/Doc-26/library/tkinter.rst doctools/trunk/Doc-26/library/urllib2.rst doctools/trunk/Doc-26/library/xml.etree.rst doctools/trunk/Doc-26/maclib/macui.rst doctools/trunk/Doc-26/maclib/scripting.rst doctools/trunk/Doc-3k/TODO doctools/trunk/Doc-3k/bugs.rst doctools/trunk/Doc-3k/c-api/concrete.rst doctools/trunk/Doc-3k/c-api/init.rst doctools/trunk/Doc-3k/c-api/utilities.rst doctools/trunk/Doc-3k/extending/windows.rst doctools/trunk/Doc-3k/library/curses.rst doctools/trunk/Doc-3k/library/decimal.rst doctools/trunk/Doc-3k/library/filesys.rst doctools/trunk/Doc-3k/library/operator.rst doctools/trunk/Doc-3k/library/optparse.rst doctools/trunk/Doc-3k/library/tkinter.rst doctools/trunk/Doc-3k/library/urllib2.rst doctools/trunk/Doc-3k/library/xml.etree.rst doctools/trunk/Doc-3k/maclib/macui.rst doctools/trunk/Doc-3k/maclib/scripting.rst doctools/trunk/sphinx/directives.py Log: Fix all instances of bad reST generated by the converter. Remove a debugging print. Modified: doctools/trunk/Doc-26/TODO ============================================================================== --- doctools/trunk/Doc-26/TODO (original) +++ doctools/trunk/Doc-26/TODO Thu Aug 2 15:06:23 2007 @@ -2,7 +2,6 @@ ====================== * fix all references and links marked with `XXX` -* adjust all literal include paths * fix all duplicate labels and undefined label references * split very large files and add toctrees * integrate standalone HOWTOs Modified: doctools/trunk/Doc-26/bugs.rst ============================================================================== --- doctools/trunk/Doc-26/bugs.rst (original) +++ doctools/trunk/Doc-26/bugs.rst Thu Aug 2 15:06:23 2007 @@ -1,9 +1,9 @@ +.. _reporting-bugs: + ************** Reporting Bugs ************** -.. _reporting-bugs: - Python is a mature programming language which has established a reputation for stability. In order to maintain this reputation, the developers would like to know of any deficiencies you find in Python or its documentation. Modified: doctools/trunk/Doc-26/c-api/concrete.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/concrete.rst (original) +++ doctools/trunk/Doc-26/c-api/concrete.rst Thu Aug 2 15:06:23 2007 @@ -3040,15 +3040,15 @@ .. cfunction:: PyObject* PyCObject_FromVoidPtr(void* cobj, void (*destr)(void *)) - Create a :ctype:`PyCObject` from the ``void *``*cobj*. The *destr* function + Create a :ctype:`PyCObject` from the ``void *`` *cobj*. The *destr* function will be called when the object is reclaimed, unless it is *NULL*. .. cfunction:: PyObject* PyCObject_FromVoidPtrAndDesc(void* cobj, void* desc, void (*destr)(void *, void *)) - Create a :ctype:`PyCObject` from the :ctype:`void \*`*cobj*. The *destr* - function will be called when the object is reclaimed. The *desc* argument can be - used to pass extra callback data for the destructor function. + Create a :ctype:`PyCObject` from the :ctype:`void \*` *cobj*. The *destr* + function will be called when the object is reclaimed. The *desc* argument can + be used to pass extra callback data for the destructor function. .. cfunction:: void* PyCObject_AsVoidPtr(PyObject* self) Modified: doctools/trunk/Doc-26/c-api/init.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/init.rst (original) +++ doctools/trunk/Doc-26/c-api/init.rst Thu Aug 2 15:06:23 2007 @@ -204,7 +204,7 @@ .. cfunction:: char* Py_GetExecPrefix() - Return the *exec-prefix* for installed platform-*de*pendent files. This is + Return the *exec-prefix* for installed platform-*dependent* files. This is derived through a number of complicated rules from the program name set with :cfunc:`Py_SetProgramName` and some environment variables; for example, if the program name is ``'/usr/local/bin/python'``, the exec-prefix is Modified: doctools/trunk/Doc-26/c-api/utilities.rst ============================================================================== --- doctools/trunk/Doc-26/c-api/utilities.rst (original) +++ doctools/trunk/Doc-26/c-api/utilities.rst Thu Aug 2 15:06:23 2007 @@ -619,9 +619,9 @@ Convert a Python object to a C variable through a *converter* function. This takes two arguments: the first is a function, the second is the address of a C variable (of arbitrary type), converted to :ctype:`void \*`. The *converter* - function in turn is called as follows: + function in turn is called as follows:: - *status*``=``*converter*``(``*object*, *address*``);`` + status = converter(object, address); where *object* is the Python object to be converted and *address* is the :ctype:`void\*` argument that was passed to the :cfunc:`PyArg_Parse\*` function. Modified: doctools/trunk/Doc-26/extending/windows.rst ============================================================================== --- doctools/trunk/Doc-26/extending/windows.rst (original) +++ doctools/trunk/Doc-26/extending/windows.rst Thu Aug 2 15:06:23 2007 @@ -68,15 +68,15 @@ #. **Build the example DLL** --- In order to check that everything is set up right, try building: -#. Select a configuration. This step is optional. Choose :menuselection:`Build - --> Configuration Manager --> Active Solution Configuration` and select either - :guilabel:`Release` or\ :guilabel:`Debug`. If you skip this step, VC++ will - use the Debug configuration by default. +#. Select a configuration. This step is optional. Choose + :menuselection:`Build --> Configuration Manager --> Active Solution Configuration` + and select either :guilabel:`Release` or :guilabel:`Debug`. If you skip this + step, VC++ will use the Debug configuration by default. #. Build the DLL. Choose :menuselection:`Build --> Build Solution`. This - creates all intermediate and result files in a subdirectory called either - :file:`Debug` or :file:`Release`, depending on which configuration you selected - in the preceding step. + creates all intermediate and result files in a subdirectory called either + :file:`Debug` or :file:`Release`, depending on which configuration you selected + in the preceding step. #. **Testing the debug-mode DLL** --- Once the Debug build has succeeded, bring up a DOS box, and change to the :file:`example_nt\\Debug` directory. You should Modified: doctools/trunk/Doc-26/library/curses.rst ============================================================================== --- doctools/trunk/Doc-26/library/curses.rst (original) +++ doctools/trunk/Doc-26/library/curses.rst Thu Aug 2 15:06:23 2007 @@ -1103,7 +1103,7 @@ Pretend *count* lines have been changed, starting with line *start*. If *changed* is supplied, it specifies whether the affected lines are marked as - having been changed (*changed*=1) or unchanged (*changed*=0). + having been changed (*changed*\ =1) or unchanged (*changed*\ =0). .. method:: window.touchwin() Modified: doctools/trunk/Doc-26/library/decimal.rst ============================================================================== --- doctools/trunk/Doc-26/library/decimal.rst (original) +++ doctools/trunk/Doc-26/library/decimal.rst Thu Aug 2 15:06:23 2007 @@ -1160,20 +1160,20 @@ Decimal FAQ ----------- -Q. It is cumbersome to type ``decimal.Decimal('1234.5')``. Is there a way to +Q. It is cumbersome to type ``decimal.Decimal('1234.5')``. Is there a way to minimize typing when using the interactive interpreter? -A. Some users abbreviate the constructor to just a single letter:: +\A. Some users abbreviate the constructor to just a single letter:: >>> D = decimal.Decimal >>> D('1.23') + D('3.45') Decimal("4.68") -Q. In a fixed-point application with two decimal places, some inputs have many +Q. In a fixed-point application with two decimal places, some inputs have many places and need to be rounded. Others are not supposed to have excess digits and need to be validated. What methods should be used? -A. The :meth:`quantize` method rounds to a fixed number of decimal places. If +A. The :meth:`quantize` method rounds to a fixed number of decimal places. If the :const:`Inexact` trap is set, it is also useful for validation:: >>> TWOPLACES = Decimal(10) ** -2 # same as Decimal('0.01') @@ -1191,36 +1191,36 @@ ... Inexact: Changed in rounding -Q. Once I have valid two place inputs, how do I maintain that invariant +Q. Once I have valid two place inputs, how do I maintain that invariant throughout an application? -A. Some operations like addition and subtraction automatically preserve fixed +A. Some operations like addition and subtraction automatically preserve fixed point. Others, like multiplication and division, change the number of decimal places and need to be followed-up with a :meth:`quantize` step. -Q. There are many ways to express the same value. The numbers :const:`200`, +Q. There are many ways to express the same value. The numbers :const:`200`, :const:`200.000`, :const:`2E2`, and :const:`.02E+4` all have the same value at various precisions. Is there a way to transform them to a single recognizable canonical value? -A. The :meth:`normalize` method maps all equivalent values to a single +A. The :meth:`normalize` method maps all equivalent values to a single representative:: >>> values = map(Decimal, '200 200.000 2E2 .02E+4'.split()) >>> [v.normalize() for v in values] [Decimal("2E+2"), Decimal("2E+2"), Decimal("2E+2"), Decimal("2E+2")] -Q. Some decimal values always print with exponential notation. Is there a way +Q. Some decimal values always print with exponential notation. Is there a way to get a non-exponential representation? -A. For some values, exponential notation is the only way to express the number +A. For some values, exponential notation is the only way to express the number of significant places in the coefficient. For example, expressing :const:`5.0E+3` as :const:`5000` keeps the value constant but cannot show the original's two-place significance. -Q. Is there a way to convert a regular float to a :class:`Decimal`? +Q. Is there a way to convert a regular float to a :class:`Decimal`? -A. Yes, all binary floating point numbers can be exactly expressed as a +A. Yes, all binary floating point numbers can be exactly expressed as a Decimal. An exact conversion may take more precision than intuition would suggest, so trapping :const:`Inexact` will signal a need for more precision:: @@ -1248,28 +1248,28 @@ finally: setcontext(oldcontext) -Q. Why isn't the :func:`floatToDecimal` routine included in the module? +Q. Why isn't the :func:`floatToDecimal` routine included in the module? -A. There is some question about whether it is advisable to mix binary and +A. There is some question about whether it is advisable to mix binary and decimal floating point. Also, its use requires some care to avoid the representation issues associated with binary floating point:: >>> floatToDecimal(1.1) Decimal("1.100000000000000088817841970012523233890533447265625") -Q. Within a complex calculation, how can I make sure that I haven't gotten a +Q. Within a complex calculation, how can I make sure that I haven't gotten a spurious result because of insufficient precision or rounding anomalies. -A. The decimal module makes it easy to test results. A best practice is to re- +A. The decimal module makes it easy to test results. A best practice is to re- run calculations using greater precision and with various rounding modes. Widely differing results indicate insufficient precision, rounding mode issues, ill- conditioned inputs, or a numerically unstable algorithm. -Q. I noticed that context precision is applied to the results of operations but +Q. I noticed that context precision is applied to the results of operations but not to the inputs. Is there anything to watch out for when mixing values of different precisions? -A. Yes. The principle is that all values are considered to be exact and so is +A. Yes. The principle is that all values are considered to be exact and so is the arithmetic on those values. Only the results are rounded. The advantage for inputs is that "what you type is what you get". A disadvantage is that the results can look odd if you forget that the inputs haven't been rounded:: Modified: doctools/trunk/Doc-26/library/dis.rst ============================================================================== --- doctools/trunk/Doc-26/library/dis.rst (original) +++ doctools/trunk/Doc-26/library/dis.rst Thu Aug 2 15:06:23 2007 @@ -189,7 +189,7 @@ .. opcode:: UNARY_CONVERT () - Implements ``TOS = `TOS``\ `. + Implements ``TOS = `TOS```. .. opcode:: UNARY_INVERT () Modified: doctools/trunk/Doc-26/library/filesys.rst ============================================================================== --- doctools/trunk/Doc-26/library/filesys.rst (original) +++ doctools/trunk/Doc-26/library/filesys.rst Thu Aug 2 15:06:23 2007 @@ -24,14 +24,13 @@ linecache.rst shutil.rst dircache.rst -Also see section :ref:`bltin-file-objects` for a description of Python's built- -in file objects. - -.. % XXX can this be included in the seealso environment? --amk .. seealso:: + Section :ref:`bltin-file-objects` + A description of Python's built-in file objects. + Module :mod:`os` Operating system interfaces, including functions to work with files at a lower level than the built-in file object. Modified: doctools/trunk/Doc-26/library/gl.rst ============================================================================== --- doctools/trunk/Doc-26/library/gl.rst (original) +++ doctools/trunk/Doc-26/library/gl.rst Thu Aug 2 15:06:23 2007 @@ -28,7 +28,7 @@ * All arrays are represented by one-dimensional Python lists. In most cases, tuples are also allowed. -* All string and character arguments are represented by Python strings, for +* All string and character arguments are represented by Python strings, for instance, ``winopen('Hi There!')`` and ``rotate(900, 'z')``. * All (short, long, unsigned) integer arguments or return values that are only Modified: doctools/trunk/Doc-26/library/operator.rst ============================================================================== --- doctools/trunk/Doc-26/library/operator.rst (original) +++ doctools/trunk/Doc-26/library/operator.rst Thu Aug 2 15:06:23 2007 @@ -90,7 +90,7 @@ .. function:: add(a, b) __add__(a, b) - Return *a* ``+`` *b*, for *a* and *b* numbers. + Return ``a + b``, for *a* and *b* numbers. .. function:: and_(a, b) @@ -102,14 +102,14 @@ .. function:: div(a, b) __div__(a, b) - Return *a* ``/`` *b* when ``__future__.division`` is not in effect. This is + Return ``a / b`` when ``__future__.division`` is not in effect. This is also known as "classic" division. .. function:: floordiv(a, b) __floordiv__(a, b) - Return *a* ``//`` *b*. + Return ``a // b``. .. versionadded:: 2.2 @@ -119,7 +119,7 @@ __inv__(o) __invert__(o) - Return the bitwise inverse of the number *o*. This is equivalent to ``~``*o*. + Return the bitwise inverse of the number *o*. This is equivalent to ``~o``. The names :func:`invert` and :func:`__invert__` were added in Python 2.0. @@ -132,13 +132,13 @@ .. function:: mod(a, b) __mod__(a, b) - Return *a* ``%`` *b*. + Return ``a % b``. .. function:: mul(a, b) __mul__(a, b) - Return *a* ``*`` *b*, for *a* and *b* numbers. + Return ``a * b``, for *a* and *b* numbers. .. function:: neg(o) @@ -162,7 +162,7 @@ .. function:: pow(a, b) __pow__(a, b) - Return *a* ``**`` *b*, for *a* and *b* numbers. + Return ``a ** b``, for *a* and *b* numbers. .. versionadded:: 2.3 @@ -176,13 +176,13 @@ .. function:: sub(a, b) __sub__(a, b) - Return *a* ``-`` *b*. + Return ``a - b``. .. function:: truediv(a, b) __truediv__(a, b) - Return *a* ``/`` *b* when ``__future__.division`` is in effect. This is also + Return ``a / b`` when ``__future__.division`` is in effect. This is also known as "true" division. .. versionadded:: 2.2 @@ -197,7 +197,7 @@ .. function:: index(a) __index__(a) - Return *a* converted to an integer. Equivalent to *a*``.__index__()``. + Return *a* converted to an integer. Equivalent to ``a.__index__()``. .. versionadded:: 2.5 @@ -207,13 +207,13 @@ .. function:: concat(a, b) __concat__(a, b) - Return *a* ``+`` *b* for *a* and *b* sequences. + Return ``a + b`` for *a* and *b* sequences. .. function:: contains(a, b) __contains__(a, b) - Return the outcome of the test *b* ``in`` *a*. Note the reversed operands. The + Return the outcome of the test ``b in a``. Note the reversed operands. The name :func:`__contains__` was added in Python 2.0. @@ -231,7 +231,7 @@ .. function:: delslice(a, b, c) __delslice__(a, b, c) - Delete the slice of *a* from index *b* to index *c*``-1``. + Delete the slice of *a* from index *b* to index *c-1*. .. function:: getitem(a, b) @@ -243,7 +243,7 @@ .. function:: getslice(a, b, c) __getslice__(a, b, c) - Return the slice of *a* from index *b* to index *c*``-1``. + Return the slice of *a* from index *b* to index *c-1*. .. function:: indexOf(a, b) @@ -254,7 +254,7 @@ .. function:: repeat(a, b) __repeat__(a, b) - Return *a* ``*`` *b* where *a* is a sequence and *b* is an integer. + Return ``a * b`` where *a* is a sequence and *b* is an integer. .. function:: sequenceIncludes(...) @@ -274,7 +274,7 @@ .. function:: setslice(a, b, c, v) __setslice__(a, b, c, v) - Set the slice of *a* from index *b* to index *c*``-1`` to the sequence *v*. + Set the slice of *a* from index *b* to index *c-1* to the sequence *v*. Many operations have an "in-place" version. The following functions provide a more primitive access to in-place operators than the usual syntax does; for @@ -405,24 +405,23 @@ .. versionadded:: 2.5 + The :mod:`operator` module also defines a few predicates to test the type of objects. .. note:: Be careful not to misinterpret the results of these functions; only - :func:`isCallable` has any measure of reliability with instance objects. For - example: - -:: + :func:`isCallable` has any measure of reliability with instance objects. + For example:: - >>> class C: - ... pass - ... - >>> import operator - >>> o = C() - >>> operator.isMappingType(o) - True + >>> class C: + ... pass + ... + >>> import operator + >>> o = C() + >>> operator.isMappingType(o) + True .. function:: isCallable(o) Modified: doctools/trunk/Doc-26/library/optparse.rst ============================================================================== --- doctools/trunk/Doc-26/library/optparse.rst (original) +++ doctools/trunk/Doc-26/library/optparse.rst Thu Aug 2 15:06:23 2007 @@ -117,18 +117,18 @@ Some other option syntaxes that the world has seen include: -* a hyphen followed by a few letters, e.g. ``"-pf"`` (this is *not* the same - as multiple options merged into a single argument) +* a hyphen followed by a few letters, e.g. ``"-pf"`` (this is *not* the same + as multiple options merged into a single argument) -* a hyphen followed by a whole word, e.g. ``"-file"`` (this is technically - equivalent to the previous syntax, but they aren't usually seen in the same - program) +* a hyphen followed by a whole word, e.g. ``"-file"`` (this is technically + equivalent to the previous syntax, but they aren't usually seen in the same + program) -* a plus sign followed by a single letter, or a few letters, or a word, e.g. - ``"+f"``, ``"+rgb"`` +* a plus sign followed by a single letter, or a few letters, or a word, e.g. + ``"+f"``, ``"+rgb"`` -* a slash followed by a letter, or a few letters, or a word, e.g. ``"/f"``, - ``"/file"`` +* a slash followed by a letter, or a few letters, or a word, e.g. ``"/f"``, + ``"/file"`` These option syntaxes are not supported by :mod:`optparse`, and they never will be. This is deliberate: the first three are non-standard on any environment, @@ -289,12 +289,12 @@ :meth:`parse_args` returns two values: -* ``options``, an object containing values for all of your options---e.g. if +* ``options``, an object containing values for all of your options---e.g. if ``"--file"`` takes a single string argument, then ``options.file`` will be the filename supplied by the user, or ``None`` if the user did not supply that option -* ``args``, the list of positional arguments leftover after parsing options +* ``args``, the list of positional arguments leftover after parsing options This tutorial section only covers the four most important option attributes: :attr:`action`, :attr:`type`, :attr:`dest` (destination), and :attr:`help`. Of @@ -510,7 +510,7 @@ There's a lot going on here to help :mod:`optparse` generate the best possible help message: -* the script defines its own usage message:: +* the script defines its own usage message:: usage = "usage: %prog [options] arg1 arg2" @@ -522,11 +522,11 @@ default: ``"usage: %prog [options]"``, which is fine if your script doesn't take any positional arguments. -* every option defines a help string, and doesn't worry about line- +* every option defines a help string, and doesn't worry about line- wrapping---\ :mod:`optparse` takes care of wrapping lines and making the help output look good. -* options that take a value indicate this fact in their automatically- +* options that take a value indicate this fact in their automatically- generated help message, e.g. for the "mode" option:: -m MODE, --mode=MODE @@ -546,7 +546,7 @@ description "write output to FILE". This is a simple but effective way to make your help text a lot clearer and more useful for end users. -* options that have a default value can include ``%default`` in the help +* options that have a default value can include ``%default`` in the help string---\ :mod:`optparse` will replace it with :func:`str` of the option's default value. If an option has no default value (or the default value is ``None``), ``%default`` expands to ``none``. @@ -737,9 +737,9 @@ :ref:`optparse-tutorial`, the tutorial. :meth:`add_option` can be called in one of two ways: -* pass it an Option instance (as returned by :func:`make_option`) +* pass it an Option instance (as returned by :func:`make_option`) -* pass it any combination of positional and keyword arguments that are +* pass it any combination of positional and keyword arguments that are acceptable to :func:`make_option` (i.e., to the Option constructor), and it will create the Option instance for you @@ -866,7 +866,7 @@ guide :mod:`optparse`'s behaviour; a few have required attributes, which you must specify for any option using that action. -* ``store`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``] +* ``store`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``] The option must be followed by an argument, which is converted to a value according to :attr:`type` and stored in :attr:`dest`. If ``nargs`` > 1, @@ -899,7 +899,7 @@ options.point = (1.0, -3.5, 4.0) options.f = "bar.txt" -* ``store_const`` [required: ``const``; relevant: :attr:`dest`] +* ``store_const`` [required: ``const``; relevant: :attr:`dest`] The value ``const`` is stored in :attr:`dest`. @@ -916,11 +916,11 @@ options.verbose = 2 -* ``store_true`` [relevant: :attr:`dest`] +* ``store_true`` [relevant: :attr:`dest`] A special case of ``store_const`` that stores a true value to :attr:`dest`. -* ``store_false`` [relevant: :attr:`dest`] +* ``store_false`` [relevant: :attr:`dest`] Like ``store_true``, but stores a false value. @@ -929,7 +929,7 @@ parser.add_option("--clobber", action="store_true", dest="clobber") parser.add_option("--no-clobber", action="store_false", dest="clobber") -* ``append`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``] +* ``append`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``] The option must be followed by an argument, which is appended to the list in :attr:`dest`. If no default value for :attr:`dest` is supplied, an empty list @@ -954,13 +954,13 @@ options.tracks.append(int("4")) -* ``append_const`` [required: ``const``; relevant: :attr:`dest`] +* ``append_const`` [required: ``const``; relevant: :attr:`dest`] Like ``store_const``, but the value ``const`` is appended to :attr:`dest`; as with ``append``, :attr:`dest` defaults to ``None``, and an an empty list is automatically created the first time the option is encountered. -* ``count`` [relevant: :attr:`dest`] +* ``count`` [relevant: :attr:`dest`] Increment the integer stored at :attr:`dest`. If no default value is supplied, :attr:`dest` is set to zero before being incremented the first time. @@ -979,7 +979,7 @@ options.verbosity += 1 -* ``callback`` [required: ``callback``; relevant: :attr:`type`, ``nargs``, +* ``callback`` [required: ``callback``; relevant: :attr:`type`, ``nargs``, ``callback_args``, ``callback_kwargs``] Call the function specified by ``callback``, which is called as :: @@ -988,7 +988,7 @@ See section :ref:`optparse-option-callbacks`, Option Callbacks for more detail. -* :attr:`help` +* :attr:`help` Prints a complete help message for all the options in the current option parser. The help message is constructed from the ``usage`` string passed to @@ -1027,7 +1027,7 @@ After printing the help message, :mod:`optparse` terminates your process with ``sys.exit(0)``. -* ``version`` +* ``version`` Prints the version number supplied to the OptionParser to stdout and exits. The version number is actually formatted and printed by the ``print_version()`` @@ -1047,59 +1047,59 @@ to a particular option, or fail to pass a required option attribute, :mod:`optparse` raises OptionError. -* :attr:`action` (default: ``"store"``) +* :attr:`action` (default: ``"store"``) Determines :mod:`optparse`'s behaviour when this option is seen on the command line; the available options are documented above. -* :attr:`type` (default: ``"string"``) +* :attr:`type` (default: ``"string"``) The argument type expected by this option (e.g., ``"string"`` or ``"int"``); the available option types are documented below. -* :attr:`dest` (default: derived from option strings) +* :attr:`dest` (default: derived from option strings) If the option's action implies writing or modifying a value somewhere, this tells :mod:`optparse` where to write it: :attr:`dest` names an attribute of the ``options`` object that :mod:`optparse` builds as it parses the command line. -* ``default`` (deprecated) +* ``default`` (deprecated) The value to use for this option's destination if the option is not seen on the command line. Deprecated; use ``parser.set_defaults()`` instead. -* ``nargs`` (default: 1) +* ``nargs`` (default: 1) How many arguments of type :attr:`type` should be consumed when this option is seen. If > 1, :mod:`optparse` will store a tuple of values to :attr:`dest`. -* ``const`` +* ``const`` For actions that store a constant value, the constant value to store. -* ``choices`` +* ``choices`` For options of type ``"choice"``, the list of strings the user may choose from. -* ``callback`` +* ``callback`` For options with action ``"callback"``, the callable to call when this option is seen. See section :ref:`optparse-option-callbacks`, Option Callbacks for detail on the arguments passed to ``callable``. -* ``callback_args``, ``callback_kwargs`` +* ``callback_args``, ``callback_kwargs`` Additional positional and keyword arguments to pass to ``callback`` after the four standard callback arguments. -* :attr:`help` +* :attr:`help` Help text to print for this option when listing all available options after the user supplies a :attr:`help` option (such as ``"--help"``). If no help text is supplied, the option will be listed without help text. To hide this option, use the special value ``SUPPRESS_HELP``. -* ``metavar`` (default: derived from option strings) +* ``metavar`` (default: derived from option strings) Stand-in for the option argument(s) to use when printing help text. See section :ref:`optparse-tutorial`, the tutorial for an example. @@ -1119,13 +1119,13 @@ Integer arguments (type ``int`` or ``long``) are parsed as follows: -* if the number starts with ``0x``, it is parsed as a hexadecimal number +* if the number starts with ``0x``, it is parsed as a hexadecimal number -* if the number starts with ``0``, it is parsed as an octal number +* if the number starts with ``0``, it is parsed as an octal number -* if the number starts with ``0b``, is is parsed as a binary number +* if the number starts with ``0b``, is is parsed as a binary number -* otherwise, the number is parsed as a decimal number +* otherwise, the number is parsed as a decimal number The conversion is done by calling either ``int()`` or ``long()`` with the @@ -1290,13 +1290,13 @@ OptionParser supports several other public methods: -* ``set_usage(usage)`` +* ``set_usage(usage)`` Set the usage string according to the rules described above for the ``usage`` constructor keyword argument. Passing ``None`` sets the default usage string; use ``SUPPRESS_USAGE`` to suppress a usage message. -* ``enable_interspersed_args()``, ``disable_interspersed_args()`` +* ``enable_interspersed_args()``, ``disable_interspersed_args()`` Enable/disable positional arguments interspersed with options, similar to GNU getopt (enabled by default). For example, if ``"-a"`` and ``"-b"`` are both @@ -1313,7 +1313,7 @@ traditional Unix syntax, where option parsing stops with the first non-option argument. -* ``set_defaults(dest=value, ...)`` +* ``set_defaults(dest=value, ...)`` Set default values for several option destinations at once. Using :meth:`set_defaults` is the preferred way to set default values for options, @@ -1351,9 +1351,9 @@ There are two steps to defining a callback option: -* define the option itself using the ``callback`` action +* define the option itself using the ``callback`` action -* write the callback; this is a function (or method) that takes at least four +* write the callback; this is a function (or method) that takes at least four arguments, as described below @@ -1586,12 +1586,12 @@ you. In particular, callbacks should implement the conventional rules for bare ``"--"`` and ``"-"`` arguments: -* either ``"--"`` or ``"-"`` can be option arguments +* either ``"--"`` or ``"-"`` can be option arguments -* bare ``"--"`` (if not the argument to some option): halt command-line +* bare ``"--"`` (if not the argument to some option): halt command-line processing and discard the ``"--"`` -* bare ``"-"`` (if not the argument to some option): halt command-line +* bare ``"-"`` (if not the argument to some option): halt command-line processing but keep the ``"-"`` (append it to ``parser.largs``) If you want an option that takes a variable number of arguments, there are @@ -1799,18 +1799,18 @@ Features of note: -* ``extend`` both expects a value on the command-line and stores that value +* ``extend`` both expects a value on the command-line and stores that value somewhere, so it goes in both :attr:`STORE_ACTIONS` and :attr:`TYPED_ACTIONS` -* to ensure that :mod:`optparse` assigns the default type of ``string`` to +* to ensure that :mod:`optparse` assigns the default type of ``string`` to ``extend`` actions, we put the ``extend`` action in ``ALWAYS_TYPED_ACTIONS`` as well -* :meth:`MyOption.take_action` implements just this one new action, and passes +* :meth:`MyOption.take_action` implements just this one new action, and passes control back to :meth:`Option.take_action` for the standard :mod:`optparse` actions -* ``values`` is an instance of the optparse_parser.Values class, which +* ``values`` is an instance of the optparse_parser.Values class, which provides the very useful :meth:`ensure_value` method. :meth:`ensure_value` is essentially :func:`getattr` with a safety valve; it is called as :: Modified: doctools/trunk/Doc-26/library/tkinter.rst ============================================================================== --- doctools/trunk/Doc-26/library/tkinter.rst (original) +++ doctools/trunk/Doc-26/library/tkinter.rst Thu Aug 2 15:06:23 2007 @@ -766,10 +766,10 @@ are commonly known as *callbacks*.) add - is optional, either ```` or``\ +``. Passing an empty string denotes that this - binding is to replace any other bindings that this event is associated with. - Preceeding with a``\ +`` means that this function is to be added to the list of - functions bound to this event type. + is optional, either ``''`` or ``'+'``. Passing an empty string denotes that + this binding is to replace any other bindings that this event is associated + with. Passing a ``'+'`` means that this function is to be added to the list + of functions bound to this event type. For example:: Modified: doctools/trunk/Doc-26/library/urllib2.rst ============================================================================== --- doctools/trunk/Doc-26/library/urllib2.rst (original) +++ doctools/trunk/Doc-26/library/urllib2.rst Thu Aug 2 15:06:23 2007 @@ -62,10 +62,10 @@ .. function:: build_opener([handler, ...]) Return an :class:`OpenerDirector` instance, which chains the handlers in the - order given. *handler*s can be either instances of :class:`BaseHandler`, or + order given. *handler*\s can be either instances of :class:`BaseHandler`, or subclasses of :class:`BaseHandler` (in which case it must be possible to call the constructor without any parameters). Instances of the following classes - will be in front of the *handler*s, unless the *handler*s contain them, + will be in front of the *handler*\s, unless the *handler*\s contain them, instances of them or subclasses of them: :class:`ProxyHandler`, :class:`UnknownHandler`, :class:`HTTPHandler`, :class:`HTTPDefaultErrorHandler`, :class:`HTTPRedirectHandler`, :class:`FTPHandler`, :class:`FileHandler`, Modified: doctools/trunk/Doc-26/library/xml.etree.rst ============================================================================== --- doctools/trunk/Doc-26/library/xml.etree.rst (original) +++ doctools/trunk/Doc-26/library/xml.etree.rst Thu Aug 2 15:06:23 2007 @@ -1,6 +1,5 @@ - -:mod:`xml.etree` --- The ElementTree API for XML -================================================= +:mod:`xml.etree` --- The ElementTree API for XML +================================================ .. module:: xml.etree :synopsis: Package containing common ElementTree modules. @@ -23,4 +22,3 @@ `ElementTree Overview <http://effbot.org/tag/elementtree>`_ The home page for :mod:`ElementTree`. This includes links to additional documentation, alternative implementations, and other add-ons. - Modified: doctools/trunk/Doc-26/maclib/macui.rst ============================================================================== --- doctools/trunk/Doc-26/maclib/macui.rst (original) +++ doctools/trunk/Doc-26/maclib/macui.rst Thu Aug 2 15:06:23 2007 @@ -77,7 +77,7 @@ options are selected. Its items can take one of two forms: *optstr* or ``(optstr, descr)``. When present, *descr* is a short descriptive string that is displayed in the dialog while this option is selected in the popup menu. The - correspondence between *optstr*s and command-line arguments is: + correspondence between *optstr*\s and command-line arguments is: +----------------------+------------------------------------------+ | *optstr* format | Command-line format | Modified: doctools/trunk/Doc-26/maclib/scripting.rst ============================================================================== --- doctools/trunk/Doc-26/maclib/scripting.rst (original) +++ doctools/trunk/Doc-26/maclib/scripting.rst Thu Aug 2 15:06:23 2007 @@ -86,12 +86,7 @@ aepack.rst aetypes.rst miniae.rst + In addition, support modules have been pre-generated for :mod:`Finder`, :mod:`Terminal`, :mod:`Explorer`, :mod:`Netscape`, :mod:`CodeWarrior`, :mod:`SystemEvents` and :mod:`StdSuites`. - -XXX: input{libgensuitemodule} :XXX -XXX: input{libaetools} :XXX -XXX: input{libaepack} :XXX -XXX: input{libaetypes} :XXX -XXX: input{libminiae} :XXX Modified: doctools/trunk/Doc-3k/TODO ============================================================================== --- doctools/trunk/Doc-3k/TODO (original) +++ doctools/trunk/Doc-3k/TODO Thu Aug 2 15:06:23 2007 @@ -2,7 +2,6 @@ ====================== * fix all references and links marked with `XXX` -* adjust all literal include paths * fix all duplicate labels and undefined label references * split very large files and add toctrees * integrate standalone HOWTOs Modified: doctools/trunk/Doc-3k/bugs.rst ============================================================================== --- doctools/trunk/Doc-3k/bugs.rst (original) +++ doctools/trunk/Doc-3k/bugs.rst Thu Aug 2 15:06:23 2007 @@ -1,9 +1,9 @@ +.. _reporting-bugs: + ************** Reporting Bugs ************** -.. _reporting-bugs: - Python is a mature programming language which has established a reputation for stability. In order to maintain this reputation, the developers would like to know of any deficiencies you find in Python or its documentation. Modified: doctools/trunk/Doc-3k/c-api/concrete.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/concrete.rst (original) +++ doctools/trunk/Doc-3k/c-api/concrete.rst Thu Aug 2 15:06:23 2007 @@ -3157,15 +3157,15 @@ .. cfunction:: PyObject* PyCObject_FromVoidPtr(void* cobj, void (*destr)(void *)) - Create a :ctype:`PyCObject` from the ``void *``*cobj*. The *destr* function + Create a :ctype:`PyCObject` from the ``void *`` *cobj*. The *destr* function will be called when the object is reclaimed, unless it is *NULL*. .. cfunction:: PyObject* PyCObject_FromVoidPtrAndDesc(void* cobj, void* desc, void (*destr)(void *, void *)) - Create a :ctype:`PyCObject` from the :ctype:`void \*`*cobj*. The *destr* - function will be called when the object is reclaimed. The *desc* argument can be - used to pass extra callback data for the destructor function. + Create a :ctype:`PyCObject` from the :ctype:`void \*` *cobj*. The *destr* + function will be called when the object is reclaimed. The *desc* argument can + be used to pass extra callback data for the destructor function. .. cfunction:: void* PyCObject_AsVoidPtr(PyObject* self) Modified: doctools/trunk/Doc-3k/c-api/init.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/init.rst (original) +++ doctools/trunk/Doc-3k/c-api/init.rst Thu Aug 2 15:06:23 2007 @@ -204,7 +204,7 @@ .. cfunction:: char* Py_GetExecPrefix() - Return the *exec-prefix* for installed platform-*de*pendent files. This is + Return the *exec-prefix* for installed platform-*dependent* files. This is derived through a number of complicated rules from the program name set with :cfunc:`Py_SetProgramName` and some environment variables; for example, if the program name is ``'/usr/local/bin/python'``, the exec-prefix is Modified: doctools/trunk/Doc-3k/c-api/utilities.rst ============================================================================== --- doctools/trunk/Doc-3k/c-api/utilities.rst (original) +++ doctools/trunk/Doc-3k/c-api/utilities.rst Thu Aug 2 15:06:23 2007 @@ -624,9 +624,9 @@ Convert a Python object to a C variable through a *converter* function. This takes two arguments: the first is a function, the second is the address of a C variable (of arbitrary type), converted to :ctype:`void \*`. The *converter* - function in turn is called as follows: + function in turn is called as follows:: - *status*``=``*converter*``(``*object*, *address*``);`` + status = converter(object, address); where *object* is the Python object to be converted and *address* is the :ctype:`void\*` argument that was passed to the :cfunc:`PyArg_Parse\*` function. Modified: doctools/trunk/Doc-3k/extending/windows.rst ============================================================================== --- doctools/trunk/Doc-3k/extending/windows.rst (original) +++ doctools/trunk/Doc-3k/extending/windows.rst Thu Aug 2 15:06:23 2007 @@ -68,15 +68,15 @@ #. **Build the example DLL** --- In order to check that everything is set up right, try building: -#. Select a configuration. This step is optional. Choose :menuselection:`Build - --> Configuration Manager --> Active Solution Configuration` and select either - :guilabel:`Release` or\ :guilabel:`Debug`. If you skip this step, VC++ will - use the Debug configuration by default. +#. Select a configuration. This step is optional. Choose + :menuselection:`Build --> Configuration Manager --> Active Solution Configuration` + and select either :guilabel:`Release` or :guilabel:`Debug`. If you skip this + step, VC++ will use the Debug configuration by default. #. Build the DLL. Choose :menuselection:`Build --> Build Solution`. This - creates all intermediate and result files in a subdirectory called either - :file:`Debug` or :file:`Release`, depending on which configuration you selected - in the preceding step. + creates all intermediate and result files in a subdirectory called either + :file:`Debug` or :file:`Release`, depending on which configuration you selected + in the preceding step. #. **Testing the debug-mode DLL** --- Once the Debug build has succeeded, bring up a DOS box, and change to the :file:`example_nt\\Debug` directory. You should Modified: doctools/trunk/Doc-3k/library/curses.rst ============================================================================== --- doctools/trunk/Doc-3k/library/curses.rst (original) +++ doctools/trunk/Doc-3k/library/curses.rst Thu Aug 2 15:06:23 2007 @@ -1103,7 +1103,7 @@ Pretend *count* lines have been changed, starting with line *start*. If *changed* is supplied, it specifies whether the affected lines are marked as - having been changed (*changed*=1) or unchanged (*changed*=0). + having been changed (*changed*\ =1) or unchanged (*changed*\ =0). .. method:: window.touchwin() Modified: doctools/trunk/Doc-3k/library/decimal.rst ============================================================================== --- doctools/trunk/Doc-3k/library/decimal.rst (original) +++ doctools/trunk/Doc-3k/library/decimal.rst Thu Aug 2 15:06:23 2007 @@ -1160,20 +1160,20 @@ Decimal FAQ ----------- -Q. It is cumbersome to type ``decimal.Decimal('1234.5')``. Is there a way to +Q. It is cumbersome to type ``decimal.Decimal('1234.5')``. Is there a way to minimize typing when using the interactive interpreter? -A. Some users abbreviate the constructor to just a single letter:: +\A. Some users abbreviate the constructor to just a single letter:: >>> D = decimal.Decimal >>> D('1.23') + D('3.45') Decimal("4.68") -Q. In a fixed-point application with two decimal places, some inputs have many +Q. In a fixed-point application with two decimal places, some inputs have many places and need to be rounded. Others are not supposed to have excess digits and need to be validated. What methods should be used? -A. The :meth:`quantize` method rounds to a fixed number of decimal places. If +A. The :meth:`quantize` method rounds to a fixed number of decimal places. If the :const:`Inexact` trap is set, it is also useful for validation:: >>> TWOPLACES = Decimal(10) ** -2 # same as Decimal('0.01') @@ -1191,36 +1191,36 @@ ... Inexact: Changed in rounding -Q. Once I have valid two place inputs, how do I maintain that invariant +Q. Once I have valid two place inputs, how do I maintain that invariant throughout an application? -A. Some operations like addition and subtraction automatically preserve fixed +A. Some operations like addition and subtraction automatically preserve fixed point. Others, like multiplication and division, change the number of decimal places and need to be followed-up with a :meth:`quantize` step. -Q. There are many ways to express the same value. The numbers :const:`200`, +Q. There are many ways to express the same value. The numbers :const:`200`, :const:`200.000`, :const:`2E2`, and :const:`.02E+4` all have the same value at various precisions. Is there a way to transform them to a single recognizable canonical value? -A. The :meth:`normalize` method maps all equivalent values to a single +A. The :meth:`normalize` method maps all equivalent values to a single representative:: >>> values = map(Decimal, '200 200.000 2E2 .02E+4'.split()) >>> [v.normalize() for v in values] [Decimal("2E+2"), Decimal("2E+2"), Decimal("2E+2"), Decimal("2E+2")] -Q. Some decimal values always print with exponential notation. Is there a way +Q. Some decimal values always print with exponential notation. Is there a way to get a non-exponential representation? -A. For some values, exponential notation is the only way to express the number +A. For some values, exponential notation is the only way to express the number of significant places in the coefficient. For example, expressing :const:`5.0E+3` as :const:`5000` keeps the value constant but cannot show the original's two-place significance. -Q. Is there a way to convert a regular float to a :class:`Decimal`? +Q. Is there a way to convert a regular float to a :class:`Decimal`? -A. Yes, all binary floating point numbers can be exactly expressed as a +A. Yes, all binary floating point numbers can be exactly expressed as a Decimal. An exact conversion may take more precision than intuition would suggest, so trapping :const:`Inexact` will signal a need for more precision:: @@ -1248,28 +1248,28 @@ finally: setcontext(oldcontext) -Q. Why isn't the :func:`floatToDecimal` routine included in the module? +Q. Why isn't the :func:`floatToDecimal` routine included in the module? -A. There is some question about whether it is advisable to mix binary and +A. There is some question about whether it is advisable to mix binary and decimal floating point. Also, its use requires some care to avoid the representation issues associated with binary floating point:: >>> floatToDecimal(1.1) Decimal("1.100000000000000088817841970012523233890533447265625") -Q. Within a complex calculation, how can I make sure that I haven't gotten a +Q. Within a complex calculation, how can I make sure that I haven't gotten a spurious result because of insufficient precision or rounding anomalies. -A. The decimal module makes it easy to test results. A best practice is to re- +A. The decimal module makes it easy to test results. A best practice is to re- run calculations using greater precision and with various rounding modes. Widely differing results indicate insufficient precision, rounding mode issues, ill- conditioned inputs, or a numerically unstable algorithm. -Q. I noticed that context precision is applied to the results of operations but +Q. I noticed that context precision is applied to the results of operations but not to the inputs. Is there anything to watch out for when mixing values of different precisions? -A. Yes. The principle is that all values are considered to be exact and so is +A. Yes. The principle is that all values are considered to be exact and so is the arithmetic on those values. Only the results are rounded. The advantage for inputs is that "what you type is what you get". A disadvantage is that the results can look odd if you forget that the inputs haven't been rounded:: Modified: doctools/trunk/Doc-3k/library/filesys.rst ============================================================================== --- doctools/trunk/Doc-3k/library/filesys.rst (original) +++ doctools/trunk/Doc-3k/library/filesys.rst Thu Aug 2 15:06:23 2007 @@ -24,14 +24,13 @@ linecache.rst shutil.rst dircache.rst -Also see section :ref:`bltin-file-objects` for a description of Python's built- -in file objects. - -.. % XXX can this be included in the seealso environment? --amk .. seealso:: + Section :ref:`bltin-file-objects` + A description of Python's built-in file objects. + Module :mod:`os` Operating system interfaces, including functions to work with files at a lower level than the built-in file object. Modified: doctools/trunk/Doc-3k/library/operator.rst ============================================================================== --- doctools/trunk/Doc-3k/library/operator.rst (original) +++ doctools/trunk/Doc-3k/library/operator.rst Thu Aug 2 15:06:23 2007 @@ -90,7 +90,7 @@ .. function:: add(a, b) __add__(a, b) - Return *a* ``+`` *b*, for *a* and *b* numbers. + Return ``a + b``, for *a* and *b* numbers. .. function:: and_(a, b) @@ -102,14 +102,14 @@ .. function:: div(a, b) __div__(a, b) - Return *a* ``/`` *b* when ``__future__.division`` is not in effect. This is + Return ``a / b`` when ``__future__.division`` is not in effect. This is also known as "classic" division. .. function:: floordiv(a, b) __floordiv__(a, b) - Return *a* ``//`` *b*. + Return ``a // b``. .. versionadded:: 2.2 @@ -119,7 +119,7 @@ __inv__(o) __invert__(o) - Return the bitwise inverse of the number *o*. This is equivalent to ``~``*o*. + Return the bitwise inverse of the number *o*. This is equivalent to ``~o``. The names :func:`invert` and :func:`__invert__` were added in Python 2.0. @@ -132,13 +132,13 @@ .. function:: mod(a, b) __mod__(a, b) - Return *a* ``%`` *b*. + Return ``a % b``. .. function:: mul(a, b) __mul__(a, b) - Return *a* ``*`` *b*, for *a* and *b* numbers. + Return ``a * b``, for *a* and *b* numbers. .. function:: neg(o) @@ -162,7 +162,7 @@ .. function:: pow(a, b) __pow__(a, b) - Return *a* ``**`` *b*, for *a* and *b* numbers. + Return ``a ** b``, for *a* and *b* numbers. .. versionadded:: 2.3 @@ -176,13 +176,13 @@ .. function:: sub(a, b) __sub__(a, b) - Return *a* ``-`` *b*. + Return ``a - b``. .. function:: truediv(a, b) __truediv__(a, b) - Return *a* ``/`` *b* when ``__future__.division`` is in effect. This is also + Return ``a / b`` when ``__future__.division`` is in effect. This is also known as "true" division. .. versionadded:: 2.2 @@ -197,7 +197,7 @@ .. function:: index(a) __index__(a) - Return *a* converted to an integer. Equivalent to *a*``.__index__()``. + Return *a* converted to an integer. Equivalent to ``a.__index__()``. .. versionadded:: 2.5 @@ -207,13 +207,13 @@ .. function:: concat(a, b) __concat__(a, b) - Return *a* ``+`` *b* for *a* and *b* sequences. + Return ``a + b`` for *a* and *b* sequences. .. function:: contains(a, b) __contains__(a, b) - Return the outcome of the test *b* ``in`` *a*. Note the reversed operands. The + Return the outcome of the test ``b in a``. Note the reversed operands. The name :func:`__contains__` was added in Python 2.0. @@ -231,7 +231,7 @@ .. function:: delslice(a, b, c) __delslice__(a, b, c) - Delete the slice of *a* from index *b* to index *c*``-1``. + Delete the slice of *a* from index *b* to index *c-1*. .. function:: getitem(a, b) @@ -243,7 +243,7 @@ .. function:: getslice(a, b, c) __getslice__(a, b, c) - Return the slice of *a* from index *b* to index *c*``-1``. + Return the slice of *a* from index *b* to index *c-1*. .. function:: indexOf(a, b) @@ -254,7 +254,7 @@ .. function:: repeat(a, b) __repeat__(a, b) - Return *a* ``*`` *b* where *a* is a sequence and *b* is an integer. + Return ``a * b`` where *a* is a sequence and *b* is an integer. .. function:: sequenceIncludes(...) @@ -274,7 +274,7 @@ .. function:: setslice(a, b, c, v) __setslice__(a, b, c, v) - Set the slice of *a* from index *b* to index *c*``-1`` to the sequence *v*. + Set the slice of *a* from index *b* to index *c-1* to the sequence *v*. Many operations have an "in-place" version. The following functions provide a more primitive access to in-place operators than the usual syntax does; for @@ -405,24 +405,23 @@ .. versionadded:: 2.5 + The :mod:`operator` module also defines a few predicates to test the type of objects. .. note:: Be careful not to misinterpret the results of these functions; only - :func:`isCallable` has any measure of reliability with instance objects. For - example: - -:: + :func:`isCallable` has any measure of reliability with instance objects. + For example:: - >>> class C: - ... pass - ... - >>> import operator - >>> o = C() - >>> operator.isMappingType(o) - True + >>> class C: + ... pass + ... + >>> import operator + >>> o = C() + >>> operator.isMappingType(o) + True .. function:: isCallable(o) Modified: doctools/trunk/Doc-3k/library/optparse.rst ============================================================================== --- doctools/trunk/Doc-3k/library/optparse.rst (original) +++ doctools/trunk/Doc-3k/library/optparse.rst Thu Aug 2 15:06:23 2007 @@ -117,18 +117,18 @@ Some other option syntaxes that the world has seen include: -* a hyphen followed by a few letters, e.g. ``"-pf"`` (this is *not* the same - as multiple options merged into a single argument) +* a hyphen followed by a few letters, e.g. ``"-pf"`` (this is *not* the same + as multiple options merged into a single argument) -* a hyphen followed by a whole word, e.g. ``"-file"`` (this is technically - equivalent to the previous syntax, but they aren't usually seen in the same - program) +* a hyphen followed by a whole word, e.g. ``"-file"`` (this is technically + equivalent to the previous syntax, but they aren't usually seen in the same + program) -* a plus sign followed by a single letter, or a few letters, or a word, e.g. - ``"+f"``, ``"+rgb"`` +* a plus sign followed by a single letter, or a few letters, or a word, e.g. + ``"+f"``, ``"+rgb"`` -* a slash followed by a letter, or a few letters, or a word, e.g. ``"/f"``, - ``"/file"`` +* a slash followed by a letter, or a few letters, or a word, e.g. ``"/f"``, + ``"/file"`` These option syntaxes are not supported by :mod:`optparse`, and they never will be. This is deliberate: the first three are non-standard on any environment, @@ -289,12 +289,12 @@ :meth:`parse_args` returns two values: -* ``options``, an object containing values for all of your options---e.g. if +* ``options``, an object containing values for all of your options---e.g. if ``"--file"`` takes a single string argument, then ``options.file`` will be the filename supplied by the user, or ``None`` if the user did not supply that option -* ``args``, the list of positional arguments leftover after parsing options +* ``args``, the list of positional arguments leftover after parsing options This tutorial section only covers the four most important option attributes: :attr:`action`, :attr:`type`, :attr:`dest` (destination), and :attr:`help`. Of @@ -510,7 +510,7 @@ There's a lot going on here to help :mod:`optparse` generate the best possible help message: -* the script defines its own usage message:: +* the script defines its own usage message:: usage = "usage: %prog [options] arg1 arg2" @@ -522,11 +522,11 @@ default: ``"usage: %prog [options]"``, which is fine if your script doesn't take any positional arguments. -* every option defines a help string, and doesn't worry about line- +* every option defines a help string, and doesn't worry about line- wrapping---\ :mod:`optparse` takes care of wrapping lines and making the help output look good. -* options that take a value indicate this fact in their automatically- +* options that take a value indicate this fact in their automatically- generated help message, e.g. for the "mode" option:: -m MODE, --mode=MODE @@ -546,7 +546,7 @@ description "write output to FILE". This is a simple but effective way to make your help text a lot clearer and more useful for end users. -* options that have a default value can include ``%default`` in the help +* options that have a default value can include ``%default`` in the help string---\ :mod:`optparse` will replace it with :func:`str` of the option's default value. If an option has no default value (or the default value is ``None``), ``%default`` expands to ``none``. @@ -737,9 +737,9 @@ :ref:`optparse-tutorial`, the tutorial. :meth:`add_option` can be called in one of two ways: -* pass it an Option instance (as returned by :func:`make_option`) +* pass it an Option instance (as returned by :func:`make_option`) -* pass it any combination of positional and keyword arguments that are +* pass it any combination of positional and keyword arguments that are acceptable to :func:`make_option` (i.e., to the Option constructor), and it will create the Option instance for you @@ -866,7 +866,7 @@ guide :mod:`optparse`'s behaviour; a few have required attributes, which you must specify for any option using that action. -* ``store`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``] +* ``store`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``] The option must be followed by an argument, which is converted to a value according to :attr:`type` and stored in :attr:`dest`. If ``nargs`` > 1, @@ -899,7 +899,7 @@ options.point = (1.0, -3.5, 4.0) options.f = "bar.txt" -* ``store_const`` [required: ``const``; relevant: :attr:`dest`] +* ``store_const`` [required: ``const``; relevant: :attr:`dest`] The value ``const`` is stored in :attr:`dest`. @@ -916,11 +916,11 @@ options.verbose = 2 -* ``store_true`` [relevant: :attr:`dest`] +* ``store_true`` [relevant: :attr:`dest`] A special case of ``store_const`` that stores a true value to :attr:`dest`. -* ``store_false`` [relevant: :attr:`dest`] +* ``store_false`` [relevant: :attr:`dest`] Like ``store_true``, but stores a false value. @@ -929,7 +929,7 @@ parser.add_option("--clobber", action="store_true", dest="clobber") parser.add_option("--no-clobber", action="store_false", dest="clobber") -* ``append`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``] +* ``append`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``] The option must be followed by an argument, which is appended to the list in :attr:`dest`. If no default value for :attr:`dest` is supplied, an empty list @@ -954,13 +954,13 @@ options.tracks.append(int("4")) -* ``append_const`` [required: ``const``; relevant: :attr:`dest`] +* ``append_const`` [required: ``const``; relevant: :attr:`dest`] Like ``store_const``, but the value ``const`` is appended to :attr:`dest`; as with ``append``, :attr:`dest` defaults to ``None``, and an an empty list is automatically created the first time the option is encountered. -* ``count`` [relevant: :attr:`dest`] +* ``count`` [relevant: :attr:`dest`] Increment the integer stored at :attr:`dest`. If no default value is supplied, :attr:`dest` is set to zero before being incremented the first time. @@ -979,7 +979,7 @@ options.verbosity += 1 -* ``callback`` [required: ``callback``; relevant: :attr:`type`, ``nargs``, +* ``callback`` [required: ``callback``; relevant: :attr:`type`, ``nargs``, ``callback_args``, ``callback_kwargs``] Call the function specified by ``callback``, which is called as :: @@ -988,7 +988,7 @@ See section :ref:`optparse-option-callbacks`, Option Callbacks for more detail. -* :attr:`help` +* :attr:`help` Prints a complete help message for all the options in the current option parser. The help message is constructed from the ``usage`` string passed to @@ -1027,7 +1027,7 @@ After printing the help message, :mod:`optparse` terminates your process with ``sys.exit(0)``. -* ``version`` +* ``version`` Prints the version number supplied to the OptionParser to stdout and exits. The version number is actually formatted and printed by the ``print_version()`` @@ -1047,59 +1047,59 @@ to a particular option, or fail to pass a required option attribute, :mod:`optparse` raises OptionError. -* :attr:`action` (default: ``"store"``) +* :attr:`action` (default: ``"store"``) Determines :mod:`optparse`'s behaviour when this option is seen on the command line; the available options are documented above. -* :attr:`type` (default: ``"string"``) +* :attr:`type` (default: ``"string"``) The argument type expected by this option (e.g., ``"string"`` or ``"int"``); the available option types are documented below. -* :attr:`dest` (default: derived from option strings) +* :attr:`dest` (default: derived from option strings) If the option's action implies writing or modifying a value somewhere, this tells :mod:`optparse` where to write it: :attr:`dest` names an attribute of the ``options`` object that :mod:`optparse` builds as it parses the command line. -* ``default`` (deprecated) +* ``default`` (deprecated) The value to use for this option's destination if the option is not seen on the command line. Deprecated; use ``parser.set_defaults()`` instead. -* ``nargs`` (default: 1) +* ``nargs`` (default: 1) How many arguments of type :attr:`type` should be consumed when this option is seen. If > 1, :mod:`optparse` will store a tuple of values to :attr:`dest`. -* ``const`` +* ``const`` For actions that store a constant value, the constant value to store. -* ``choices`` +* ``choices`` For options of type ``"choice"``, the list of strings the user may choose from. -* ``callback`` +* ``callback`` For options with action ``"callback"``, the callable to call when this option is seen. See section :ref:`optparse-option-callbacks`, Option Callbacks for detail on the arguments passed to ``callable``. -* ``callback_args``, ``callback_kwargs`` +* ``callback_args``, ``callback_kwargs`` Additional positional and keyword arguments to pass to ``callback`` after the four standard callback arguments. -* :attr:`help` +* :attr:`help` Help text to print for this option when listing all available options after the user supplies a :attr:`help` option (such as ``"--help"``). If no help text is supplied, the option will be listed without help text. To hide this option, use the special value ``SUPPRESS_HELP``. -* ``metavar`` (default: derived from option strings) +* ``metavar`` (default: derived from option strings) Stand-in for the option argument(s) to use when printing help text. See section :ref:`optparse-tutorial`, the tutorial for an example. @@ -1119,13 +1119,13 @@ Integer arguments (type ``int`` or ``long``) are parsed as follows: -* if the number starts with ``0x``, it is parsed as a hexadecimal number +* if the number starts with ``0x``, it is parsed as a hexadecimal number -* if the number starts with ``0``, it is parsed as an octal number +* if the number starts with ``0``, it is parsed as an octal number -* if the number starts with ``0b``, is is parsed as a binary number +* if the number starts with ``0b``, is is parsed as a binary number -* otherwise, the number is parsed as a decimal number +* otherwise, the number is parsed as a decimal number The conversion is done by calling either ``int()`` or ``long()`` with the @@ -1290,13 +1290,13 @@ OptionParser supports several other public methods: -* ``set_usage(usage)`` +* ``set_usage(usage)`` Set the usage string according to the rules described above for the ``usage`` constructor keyword argument. Passing ``None`` sets the default usage string; use ``SUPPRESS_USAGE`` to suppress a usage message. -* ``enable_interspersed_args()``, ``disable_interspersed_args()`` +* ``enable_interspersed_args()``, ``disable_interspersed_args()`` Enable/disable positional arguments interspersed with options, similar to GNU getopt (enabled by default). For example, if ``"-a"`` and ``"-b"`` are both @@ -1313,7 +1313,7 @@ traditional Unix syntax, where option parsing stops with the first non-option argument. -* ``set_defaults(dest=value, ...)`` +* ``set_defaults(dest=value, ...)`` Set default values for several option destinations at once. Using :meth:`set_defaults` is the preferred way to set default values for options, @@ -1351,9 +1351,9 @@ There are two steps to defining a callback option: -* define the option itself using the ``callback`` action +* define the option itself using the ``callback`` action -* write the callback; this is a function (or method) that takes at least four +* write the callback; this is a function (or method) that takes at least four arguments, as described below @@ -1586,12 +1586,12 @@ you. In particular, callbacks should implement the conventional rules for bare ``"--"`` and ``"-"`` arguments: -* either ``"--"`` or ``"-"`` can be option arguments +* either ``"--"`` or ``"-"`` can be option arguments -* bare ``"--"`` (if not the argument to some option): halt command-line +* bare ``"--"`` (if not the argument to some option): halt command-line processing and discard the ``"--"`` -* bare ``"-"`` (if not the argument to some option): halt command-line +* bare ``"-"`` (if not the argument to some option): halt command-line processing but keep the ``"-"`` (append it to ``parser.largs``) If you want an option that takes a variable number of arguments, there are @@ -1799,18 +1799,18 @@ Features of note: -* ``extend`` both expects a value on the command-line and stores that value +* ``extend`` both expects a value on the command-line and stores that value somewhere, so it goes in both :attr:`STORE_ACTIONS` and :attr:`TYPED_ACTIONS` -* to ensure that :mod:`optparse` assigns the default type of ``string`` to +* to ensure that :mod:`optparse` assigns the default type of ``string`` to ``extend`` actions, we put the ``extend`` action in ``ALWAYS_TYPED_ACTIONS`` as well -* :meth:`MyOption.take_action` implements just this one new action, and passes +* :meth:`MyOption.take_action` implements just this one new action, and passes control back to :meth:`Option.take_action` for the standard :mod:`optparse` actions -* ``values`` is an instance of the optparse_parser.Values class, which +* ``values`` is an instance of the optparse_parser.Values class, which provides the very useful :meth:`ensure_value` method. :meth:`ensure_value` is essentially :func:`getattr` with a safety valve; it is called as :: Modified: doctools/trunk/Doc-3k/library/tkinter.rst ============================================================================== --- doctools/trunk/Doc-3k/library/tkinter.rst (original) +++ doctools/trunk/Doc-3k/library/tkinter.rst Thu Aug 2 15:06:23 2007 @@ -766,10 +766,10 @@ are commonly known as *callbacks*.) add - is optional, either ```` or``\ +``. Passing an empty string denotes that this - binding is to replace any other bindings that this event is associated with. - Preceeding with a``\ +`` means that this function is to be added to the list of - functions bound to this event type. + is optional, either ``''`` or ``'+'``. Passing an empty string denotes that + this binding is to replace any other bindings that this event is associated + with. Passing a ``'+'`` means that this function is to be added to the list + of functions bound to this event type. For example:: Modified: doctools/trunk/Doc-3k/library/urllib2.rst ============================================================================== --- doctools/trunk/Doc-3k/library/urllib2.rst (original) +++ doctools/trunk/Doc-3k/library/urllib2.rst Thu Aug 2 15:06:23 2007 @@ -62,10 +62,10 @@ .. function:: build_opener([handler, ...]) Return an :class:`OpenerDirector` instance, which chains the handlers in the - order given. *handler*s can be either instances of :class:`BaseHandler`, or + order given. *handler*\s can be either instances of :class:`BaseHandler`, or subclasses of :class:`BaseHandler` (in which case it must be possible to call the constructor without any parameters). Instances of the following classes - will be in front of the *handler*s, unless the *handler*s contain them, + will be in front of the *handler*\s, unless the *handler*\s contain them, instances of them or subclasses of them: :class:`ProxyHandler`, :class:`UnknownHandler`, :class:`HTTPHandler`, :class:`HTTPDefaultErrorHandler`, :class:`HTTPRedirectHandler`, :class:`FTPHandler`, :class:`FileHandler`, Modified: doctools/trunk/Doc-3k/library/xml.etree.rst ============================================================================== --- doctools/trunk/Doc-3k/library/xml.etree.rst (original) +++ doctools/trunk/Doc-3k/library/xml.etree.rst Thu Aug 2 15:06:23 2007 @@ -1,6 +1,5 @@ - -:mod:`xml.etree` --- The ElementTree API for XML -================================================= +:mod:`xml.etree` --- The ElementTree API for XML +================================================ .. module:: xml.etree :synopsis: Package containing common ElementTree modules. Modified: doctools/trunk/Doc-3k/maclib/macui.rst ============================================================================== --- doctools/trunk/Doc-3k/maclib/macui.rst (original) +++ doctools/trunk/Doc-3k/maclib/macui.rst Thu Aug 2 15:06:23 2007 @@ -77,7 +77,7 @@ options are selected. Its items can take one of two forms: *optstr* or ``(optstr, descr)``. When present, *descr* is a short descriptive string that is displayed in the dialog while this option is selected in the popup menu. The - correspondence between *optstr*s and command-line arguments is: + correspondence between *optstr*\s and command-line arguments is: +----------------------+------------------------------------------+ | *optstr* format | Command-line format | Modified: doctools/trunk/Doc-3k/maclib/scripting.rst ============================================================================== --- doctools/trunk/Doc-3k/maclib/scripting.rst (original) +++ doctools/trunk/Doc-3k/maclib/scripting.rst Thu Aug 2 15:06:23 2007 @@ -86,12 +86,7 @@ aepack.rst aetypes.rst miniae.rst + In addition, support modules have been pre-generated for :mod:`Finder`, :mod:`Terminal`, :mod:`Explorer`, :mod:`Netscape`, :mod:`CodeWarrior`, :mod:`SystemEvents` and :mod:`StdSuites`. - -XXX: input{libgensuitemodule} :XXX -XXX: input{libaetools} :XXX -XXX: input{libaepack} :XXX -XXX: input{libaetypes} :XXX -XXX: input{libminiae} :XXX Modified: doctools/trunk/sphinx/directives.py ============================================================================== --- doctools/trunk/sphinx/directives.py (original) +++ doctools/trunk/sphinx/directives.py Thu Aug 2 15:06:23 2007 @@ -416,7 +416,6 @@ pos = m.end() if pos < len(text): retnodes.append(nodes.Text(text[pos:], text[pos:])) - print retnodes return retnodes def productionlist_directive(name, arguments, options, content, lineno,

1 0

r56666 - in doctools/trunk: Doc-26/TODO Doc-26/documenting/markup.rst Doc-26/install/index.rst Doc-26/reference/compound_stmts.rst Doc-26/reference/expressions.rst Doc-26/reference/introduction.rst Doc-26/reference/lexical_analysis.rst Doc-26/reference/simple_stmts.rst Doc-26/reference/toplevel_components.rst Doc-3k/TODO Doc-3k/documenting/markup.rst Doc-3k/install/index.rst Doc-3k/reference/compound_stmts.rst Doc-3k/reference/expressions.rst Doc-3k/reference/introduction.rst Doc-3k/refere
by georg.brandl Aug. 2, 2007

Aug. 2, 2007

Author: georg.brandl Date: Thu Aug 2 14:32:13 2007 New Revision: 56666 Modified: doctools/trunk/Doc-26/TODO doctools/trunk/Doc-26/documenting/markup.rst doctools/trunk/Doc-26/install/index.rst doctools/trunk/Doc-26/reference/compound_stmts.rst doctools/trunk/Doc-26/reference/expressions.rst doctools/trunk/Doc-26/reference/introduction.rst doctools/trunk/Doc-26/reference/lexical_analysis.rst doctools/trunk/Doc-26/reference/simple_stmts.rst doctools/trunk/Doc-26/reference/toplevel_components.rst doctools/trunk/Doc-3k/TODO doctools/trunk/Doc-3k/documenting/markup.rst doctools/trunk/Doc-3k/install/index.rst doctools/trunk/Doc-3k/reference/compound_stmts.rst doctools/trunk/Doc-3k/reference/expressions.rst doctools/trunk/Doc-3k/reference/introduction.rst doctools/trunk/Doc-3k/reference/lexical_analysis.rst doctools/trunk/Doc-3k/reference/simple_stmts.rst doctools/trunk/Doc-3k/reference/toplevel_components.rst Log: Fix production list escaping. Modified: doctools/trunk/Doc-26/TODO ============================================================================== --- doctools/trunk/Doc-26/TODO (original) +++ doctools/trunk/Doc-26/TODO Thu Aug 2 14:32:13 2007 @@ -3,14 +3,11 @@ * fix all references and links marked with `XXX` * adjust all literal include paths -* remove all non-literal includes * fix all duplicate labels and undefined label references * split very large files and add toctrees * integrate standalone HOWTOs * find out which files get "comments disabled" metadata -* double backslashes in production lists * add synopses for each module * write "About these documents" * finish "Documenting Python" * extend copyright.rst -* fix :file: and |version| in install Modified: doctools/trunk/Doc-26/documenting/markup.rst ============================================================================== --- doctools/trunk/Doc-26/documenting/markup.rst (original) +++ doctools/trunk/Doc-26/documenting/markup.rst Thu Aug 2 14:32:13 2007 @@ -673,7 +673,7 @@ triple Likewise, ``triple: module; search; path`` is a shortcut that creates three index entries, which are ``module; search path``, ``search; path, module`` and - ``path; module search``. + ``path; module search``. module, keyword, operator, object, exception, statement, builtin These all create two index entries. For example, ``module: hashlib`` creates the entries ``module; hashlib`` and ``hashlib; module``. @@ -700,9 +700,10 @@ The definition can contain token names which are marked as interpreted text (e.g. ``sum ::= `integer` "+" `integer```) -- this generates cross-references - to the productions of these tokens. Note that vertical bars used to indicate - alternatives must be escaped with backslashes because otherwise they would - indicate a substitution reference to the reST parser. + to the productions of these tokens. + + Note that no further reST parsing is done in the production, so that you + don't have to escape ``*`` or ``|`` characters. .. XXX describe optional first parameter @@ -710,13 +711,13 @@ The following is an example taken from the Python Reference Manual:: .. productionlist:: - try_stmt: try1_stmt \| try2_stmt - try1_stmt: "try" ":" :token:`suite` - : ("except" [:token:`expression` ["," :token:`target`]] ":" :token:`suite`)+ - : ["else" ":" :token:`suite`] - : ["finally" ":" :token:`suite`] - try2_stmt: "try" ":" :token:`suite` - : "finally" ":" :token:`suite` + try_stmt: try1_stmt | try2_stmt + try1_stmt: "try" ":" `suite` + : ("except" [`expression` ["," `target`]] ":" `suite`)+ + : ["else" ":" `suite`] + : ["finally" ":" `suite`] + try2_stmt: "try" ":" `suite` + : "finally" ":" `suite` Substitutions Modified: doctools/trunk/Doc-26/install/index.rst ============================================================================== --- doctools/trunk/Doc-26/install/index.rst (original) +++ doctools/trunk/Doc-26/install/index.rst Thu Aug 2 14:32:13 2007 @@ -246,19 +246,15 @@ Unix-based), it also depends on whether the module distribution being installed is pure Python or contains extensions ("non-pure"): -+-----------------+------------------------------------+--------------------------------------+-------+ -| Platform | Standard installation | Default value | Notes | -| | location | | | -+=================+====================================+======================================+=======+ -| Unix (pure) | :file:`{prefix}/lib/python|version | :file:`/usr/local/lib/python|version | \(1) | -| | |/site-packages` | |/site-packages` | | -+-----------------+------------------------------------+--------------------------------------+-------+ -| Unix (non-pure) | :file:`{exec- | :file:`/usr/local/lib/python|version | \(1) | -| | prefix}/lib/python|version | |/site-packages` | | -| | |/site-packages` | | | -+-----------------+------------------------------------+--------------------------------------+-------+ -| Windows | :file:`{prefix}` | :file:`C:\\Python` | \(2) | -+-----------------+------------------------------------+--------------------------------------+-------+ ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ +| Platform | Standard installation location | Default value | Notes | ++=================+=====================================================+==================================================+=======+ +| Unix (pure) | :file:`{prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1) | ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ +| Unix (non-pure) | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1) | ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ +| Windows | :file:`{prefix}` | :file:`C:\\Python` | \(2) | ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ Notes: @@ -346,17 +342,17 @@ The :option:`--home` option defines the installation base directory. Files are installed to the following directories under the installation base as follows: -+------------------------------+-----------------------------------+-----------------------------+ -| Type of file | Installation Directory | Override option | -+==============================+===================================+=============================+ -| pure module distribution | :file:`{home}`:file:`/lib/python` | :option:`--install-purelib` | -+------------------------------+-----------------------------------+-----------------------------+ -| non-pure module distribution | :file:`{home}`:file:`/lib/python` | :option:`--install-platlib` | -+------------------------------+-----------------------------------+-----------------------------+ -| scripts | :file:`{home}`:file:`/bin` | :option:`--install-scripts` | -+------------------------------+-----------------------------------+-----------------------------+ -| data | :file:`{home}`:file:`/share` | :option:`--install-data` | -+------------------------------+-----------------------------------+-----------------------------+ ++------------------------------+---------------------------+-----------------------------+ +| Type of file | Installation Directory | Override option | ++==============================+===========================+=============================+ +| pure module distribution | :file:`{home}/lib/python` | :option:`--install-purelib` | ++------------------------------+---------------------------+-----------------------------+ +| non-pure module distribution | :file:`{home}/lib/python` | :option:`--install-platlib` | ++------------------------------+---------------------------+-----------------------------+ +| scripts | :file:`{home}/bin` | :option:`--install-scripts` | ++------------------------------+---------------------------+-----------------------------+ +| data | :file:`{home}/share` | :option:`--install-data` | ++------------------------------+---------------------------+-----------------------------+ .. versionchanged:: 2.4 The :option:`--home` option used to be supported only on Unix. @@ -399,20 +395,17 @@ executables, etc.) If :option:`--exec-prefix` is not supplied, it defaults to :option:`--prefix`. Files are installed as follows: -+------------------------------+----------------------------------------+-----------------------------+ -| Type of file | Installation Directory | Override option | -+==============================+========================================+=============================+ -| pure module distribution | :file:`{prefix}`:file:`/lib/python2.{X | :option:`--install-purelib` | -| | }/site-packages` | | -+------------------------------+----------------------------------------+-----------------------------+ -| non-pure module distribution | :file:`{exec- | :option:`--install-platlib` | -| | prefix}`:file:`/lib/python2.{X | | -| | }/site-packages` | | -+------------------------------+----------------------------------------+-----------------------------+ -| scripts | :file:`{prefix}`:file:`/bin` | :option:`--install-scripts` | -+------------------------------+----------------------------------------+-----------------------------+ -| data | :file:`{prefix}`:file:`/share` | :option:`--install-data` | -+------------------------------+----------------------------------------+-----------------------------+ ++------------------------------+-----------------------------------------------------+-----------------------------+ +| Type of file | Installation Directory | Override option | ++==============================+=====================================================+=============================+ +| pure module distribution | :file:`{prefix}/lib/python{X.Y}/site-packages` | :option:`--install-purelib` | ++------------------------------+-----------------------------------------------------+-----------------------------+ +| non-pure module distribution | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :option:`--install-platlib` | ++------------------------------+-----------------------------------------------------+-----------------------------+ +| scripts | :file:`{prefix}/bin` | :option:`--install-scripts` | ++------------------------------+-----------------------------------------------------+-----------------------------+ +| data | :file:`{prefix}/share` | :option:`--install-data` | ++------------------------------+-----------------------------------------------------+-----------------------------+ There is no requirement that :option:`--prefix` or :option:`--exec-prefix` actually point to an alternate Python installation; if the directories listed @@ -455,17 +448,17 @@ :option:`--exec-prefix` option is not supported under Windows. Files are installed as follows: -+------------------------------+-----------------------------------+-----------------------------+ -| Type of file | Installation Directory | Override option | -+==============================+===================================+=============================+ -| pure module distribution | :file:`{prefix}`:file:`` | :option:`--install-purelib` | -+------------------------------+-----------------------------------+-----------------------------+ -| non-pure module distribution | :file:`{prefix}`:file:`` | :option:`--install-platlib` | -+------------------------------+-----------------------------------+-----------------------------+ -| scripts | :file:`{prefix}`:file:`\\Scripts` | :option:`--install-scripts` | -+------------------------------+-----------------------------------+-----------------------------+ -| data | :file:`{prefix}`:file:`\\Data` | :option:`--install-data` | -+------------------------------+-----------------------------------+-----------------------------+ ++------------------------------+---------------------------+-----------------------------+ +| Type of file | Installation Directory | Override option | ++==============================+===========================+=============================+ +| pure module distribution | :file:`{prefix}` | :option:`--install-purelib` | ++------------------------------+---------------------------+-----------------------------+ +| non-pure module distribution | :file:`{prefix}` | :option:`--install-platlib` | ++------------------------------+---------------------------+-----------------------------+ +| scripts | :file:`{prefix}\\Scripts` | :option:`--install-scripts` | ++------------------------------+---------------------------+-----------------------------+ +| data | :file:`{prefix}\\Data` | :option:`--install-data` | ++------------------------------+---------------------------+-----------------------------+ .. _custom-install: @@ -625,12 +618,12 @@ .. % $ <-- bow to font-lock The expected convention for locally installed packages is to put them in the -:file:`.../site-packages/` directory, but you may want to install Python modules -into some arbitrary directory. For example, your site may have a convention of -keeping all software related to the web server under :file:`/www`. Add-on -Python modules might then belong in :file:`/www/python`, and in order to import -them, this directory must be added to ``sys.path``. There are several different -ways to add the directory. +:file:`{...}/site-packages/` directory, but you may want to install Python +modules into some arbitrary directory. For example, your site may have a +convention of keeping all software related to the web server under :file:`/www`. +Add-on Python modules might then belong in :file:`/www/python`, and in order to +import them, this directory must be added to ``sys.path``. There are several +different ways to add the directory. The most convenient way is to add a path configuration file to a directory that's already on Python's path, usually to the :file:`.../site-packages/` @@ -921,7 +914,7 @@ The :file:`coff2omf` program comes with the Borland compiler. The file :file:`python25.lib` is in the :file:`Libs` directory of your Python -installation. If your extension uses other libraries (zlib,...) you have to +installation. If your extension uses other libraries (zlib, ...) you have to convert them too. The converted files have to reside in the same directories as the normal Modified: doctools/trunk/Doc-26/reference/compound_stmts.rst ============================================================================== --- doctools/trunk/Doc-26/reference/compound_stmts.rst (original) +++ doctools/trunk/Doc-26/reference/compound_stmts.rst Thu Aug 2 14:32:13 2007 @@ -44,15 +44,15 @@ .. productionlist:: compound_stmt: `if_stmt` - : \| `while_stmt` - : \| `for_stmt` - : \| `try_stmt` - : \| `with_stmt` - : \| `funcdef` - : \| `classdef` - suite: `stmt_list` NEWLINE \| NEWLINE INDENT `statement`\ + DEDENT - statement: `stmt_list` NEWLINE \| `compound_stmt` - stmt_list: `simple_stmt` (";" `simple_stmt`)\* [";"] + : | `while_stmt` + : | `for_stmt` + : | `try_stmt` + : | `with_stmt` + : | `funcdef` + : | `classdef` + suite: `stmt_list` NEWLINE | NEWLINE INDENT `statement`+ DEDENT + statement: `stmt_list` NEWLINE | `compound_stmt` + stmt_list: `simple_stmt` (";" `simple_stmt`)* [";"] .. index:: single: NEWLINE token @@ -80,7 +80,7 @@ .. productionlist:: if_stmt: "if" `expression` ":" `suite` - : ( "elif" `expression` ":" `suite` )\* + : ( "elif" `expression` ":" `suite` )* : ["else" ":" `suite`] .. index:: @@ -216,7 +216,7 @@ for a group of statements: .. productionlist:: - try_stmt: try1_stmt \| try2_stmt + try_stmt: try1_stmt | try2_stmt try1_stmt: "try" ":" `suite` : ("except" [`expression` ["," `target`]] ":" `suite`)+ : ["else" ":" `suite`] @@ -403,16 +403,16 @@ .. productionlist:: funcdef: [`decorators`] "def" `funcname` "(" [`parameter_list`] ")" ":" `suite` - decorators: `decorator`\ + + decorators: `decorator`+ decorator: "@" `dotted_name` ["(" [`argument_list` [","]] ")"] NEWLINE - dotted_name: `identifier` ("." `identifier`)\* - parameter_list: (`defparameter` ",")\* - : ( "\*" `identifier` [, "\*\*" `identifier`] - : \| "\*\*" `identifier` - : \| `defparameter` [","] ) + dotted_name: `identifier` ("." `identifier`)* + parameter_list: (`defparameter` ",")* + : ( "*" `identifier` [, "**" `identifier`] + : | "**" `identifier` + : | `defparameter` [","] ) defparameter: `parameter` ["=" `expression`] - sublist: `parameter` ("," `parameter`)\* [","] - parameter: `identifier` \| "(" `sublist` ")" + sublist: `parameter` ("," `parameter`)* [","] + parameter: `identifier` | "(" `sublist` ")" funcname: `identifier` .. index:: Modified: doctools/trunk/Doc-26/reference/expressions.rst ============================================================================== --- doctools/trunk/Doc-26/reference/expressions.rst (original) +++ doctools/trunk/Doc-26/reference/expressions.rst Thu Aug 2 14:32:13 2007 @@ -63,10 +63,10 @@ atoms is: .. productionlist:: - atom: `identifier` \| `literal` \| `enclosure` - enclosure: `parenth_form` \| `list_display` - : \| `generator_expression` \| `dict_display` - : \| `string_conversion` \| `yield_atom` + atom: `identifier` | `literal` | `enclosure` + enclosure: `parenth_form` | `list_display` + : | `generator_expression` | `dict_display` + : | `string_conversion` | `yield_atom` .. _atom-identifiers: @@ -119,8 +119,8 @@ Python supports string literals and various numeric literals: .. productionlist:: - literal: `stringliteral` \| `integer` \| `longinteger` - : \| `floatnumber` \| `imagnumber` + literal: `stringliteral` | `integer` | `longinteger` + : | `floatnumber` | `imagnumber` Evaluation of a literal yields an object of the given type (string, integer, long integer, floating point number, complex number) with the given value. The @@ -183,11 +183,11 @@ brackets: .. productionlist:: - list_display: "[" [`expression_list` \| `list_comprehension`] "]" + list_display: "[" [`expression_list` | `list_comprehension`] "]" list_comprehension: `expression` `list_for` list_for: "for" `target_list` "in" `old_expression_list` [`list_iter`] old_expression_list: `old_expression` [("," `old_expression`)+ [","]] - list_iter: `list_for` \| `list_if` + list_iter: `list_for` | `list_if` list_if: "if" `old_expression` [`list_iter`] .. index:: @@ -219,7 +219,7 @@ .. productionlist:: generator_expression: "(" `expression` `genexpr_for` ")" genexpr_for: "for" `target_list` "in" `or_test` [`genexpr_iter`] - genexpr_iter: `genexpr_for` \| `genexpr_if` + genexpr_iter: `genexpr_for` | `genexpr_if` genexpr_if: "if" `old_expression` [`genexpr_iter`] .. index:: object: generator @@ -262,7 +262,7 @@ .. productionlist:: dict_display: "{" [`key_datum_list`] "}" - key_datum_list: `key_datum` ("," `key_datum`)\* [","] + key_datum_list: `key_datum` ("," `key_datum`)* [","] key_datum: `expression` ":" `expression` .. index:: object: dictionary @@ -470,7 +470,7 @@ syntax is: .. productionlist:: - primary: `atom` \| `attributeref` \| `subscription` \| `slicing` \| `call` + primary: `atom` | `attributeref` | `subscription` | `slicing` | `call` .. _attribute-references: @@ -562,12 +562,12 @@ :keyword:`del` statements. The syntax for a slicing: .. productionlist:: - slicing: `simple_slicing` \| `extended_slicing` + slicing: `simple_slicing` | `extended_slicing` simple_slicing: `primary` "[" `short_slice` "]" extended_slicing: `primary` "[" `slice_list` "]" - slice_list: `slice_item` ("," `slice_item`)\* [","] - slice_item: `expression` \| `proper_slice` \| `ellipsis` - proper_slice: `short_slice` \| `long_slice` + slice_list: `slice_item` ("," `slice_item`)* [","] + slice_item: `expression` | `proper_slice` | `ellipsis` + proper_slice: `short_slice` | `long_slice` short_slice: [`lower_bound`] ":" [`upper_bound`] long_slice: `short_slice` ":" [`stride`] lower_bound: `expression` @@ -627,16 +627,16 @@ .. productionlist:: call: `primary` "(" [`argument_list` [","] - : \| `expression` `genexpr_for`] ")" + : | `expression` `genexpr_for`] ")" argument_list: `positional_arguments` ["," `keyword_arguments`] - : ["," "\*" `expression`] - : ["," "\*\*" `expression`] - : \| `keyword_arguments` ["," "\*" `expression`] - : ["," "\*\*" `expression`] - : \| "\*" `expression` ["," "\*\*" `expression`] - : \| "\*\*" `expression` - positional_arguments: `expression` ("," `expression`)\* - keyword_arguments: `keyword_item` ("," `keyword_item`)\* + : ["," "*" `expression`] + : ["," "**" `expression`] + : | `keyword_arguments` ["," "*" `expression`] + : ["," "**" `expression`] + : | "*" `expression` ["," "**" `expression`] + : | "**" `expression` + positional_arguments: `expression` ("," `expression`)* + keyword_arguments: `keyword_item` ("," `keyword_item`)* keyword_item: `identifier` "=" `expression` A trailing comma may be present after the positional and keyword arguments but @@ -786,7 +786,7 @@ less tightly than unary operators on its right. The syntax is: .. productionlist:: - power: `primary` ["\*\*" `u_expr`] + power: `primary` ["**" `u_expr`] Thus, in an unparenthesized sequence of power and unary operators, the operators are evaluated from right to left (this does not constrain the evaluation order @@ -822,7 +822,7 @@ All unary arithmetic (and bit-wise) operations have the same priority: .. productionlist:: - u_expr: `power` \| "-" `u_expr` \| "+" `u_expr` \| "~" `u_expr` + u_expr: `power` | "-" `u_expr` | "+" `u_expr` | "~" `u_expr` .. index:: single: negation @@ -859,9 +859,9 @@ operators and one for additive operators: .. productionlist:: - m_expr: `u_expr` \| `m_expr` "\*" `u_expr` \| `m_expr` "//" `u_expr` \| `m_expr` "/" `u_expr` - : \| `m_expr` "%" `u_expr` - a_expr: `m_expr` \| `a_expr` "+" `m_expr` \| `a_expr` "-" `m_expr` + m_expr: `u_expr` | `m_expr` "*" `u_expr` | `m_expr` "//" `u_expr` | `m_expr` "/" `u_expr` + : | `m_expr` "%" `u_expr` + a_expr: `m_expr` | `a_expr` "+" `m_expr` | `a_expr` "-" `m_expr` .. index:: single: multiplication @@ -934,7 +934,7 @@ The shifting operations have lower priority than the arithmetic operations: .. productionlist:: - shift_expr: `a_expr` \| `shift_expr` ( "<<" \| ">>" ) `a_expr` + shift_expr: `a_expr` | `shift_expr` ( "<<" | ">>" ) `a_expr` These operators accept plain or long integers as arguments. The arguments are converted to a common type. They shift the first argument to the left or right @@ -959,9 +959,9 @@ Each of the three bitwise operations has a different priority level: .. productionlist:: - and_expr: `shift_expr` \| `and_expr` "&" `shift_expr` - xor_expr: `and_expr` \| `xor_expr` "^" `and_expr` - or_expr: `xor_expr` \| `or_expr` "\|" `xor_expr` + and_expr: `shift_expr` | `and_expr` "&" `shift_expr` + xor_expr: `and_expr` | `xor_expr` "^" `and_expr` + or_expr: `xor_expr` | `or_expr` "|" `xor_expr` .. index:: pair: bit-wise; and @@ -998,9 +998,9 @@ in mathematics: .. productionlist:: - comparison: `or_expr` ( `comp_operator` `or_expr` )\* - comp_operator: "<" \| ">" \| "==" \| ">=" \| "<=" \| "<>" \| "!=" - : \| "is" ["not"] \| ["not"] "in" + comparison: `or_expr` ( `comp_operator` `or_expr` )* + comp_operator: "<" | ">" | "==" | ">=" | "<=" | "<>" | "!=" + : | "is" ["not"] | ["not"] "in" Comparisons yield boolean values: ``True`` or ``False``. @@ -1124,12 +1124,12 @@ Boolean operations have the lowest priority of all Python operations: .. productionlist:: - expression: `conditional_expression` \| `lambda_form` - old_expression: `or_test` \| `old_lambda_form` + expression: `conditional_expression` | `lambda_form` + old_expression: `or_test` | `old_lambda_form` conditional_expression: `or_test` ["if" `or_test` "else" `expression`] - or_test: `and_test` \| `or_test` "or" `and_test` - and_test: `not_test` \| `and_test` "and" `not_test` - not_test: `comparison` \| "not" `not_test` + or_test: `and_test` | `or_test` "or" `and_test` + and_test: `not_test` | `and_test` "and" `not_test` + not_test: `comparison` | "not" `not_test` In the context of Boolean operations, and also when expressions are used by control flow statements, the following values are interpreted as false: @@ -1203,7 +1203,7 @@ .. index:: pair: expression; list .. productionlist:: - expression_list: `expression` ( "," `expression` )\* [","] + expression_list: `expression` ( "," `expression` )* [","] .. index:: object: tuple @@ -1306,7 +1306,7 @@ +-----------------------------------------------+-------------------------------------+ | ``{key:datum...}`` | Dictionary display | +-----------------------------------------------+-------------------------------------+ -| ```expressions...``\ ` | String conversion | +| ```expressions...``` | String conversion | +-----------------------------------------------+-------------------------------------+ .. rubric:: Footnotes Modified: doctools/trunk/Doc-26/reference/introduction.rst ============================================================================== --- doctools/trunk/Doc-26/reference/introduction.rst (original) +++ doctools/trunk/Doc-26/reference/introduction.rst Thu Aug 2 14:32:13 2007 @@ -98,7 +98,7 @@ notation. This uses the following style of definition: .. productionlist:: * - name: `lc_letter` (`lc_letter` \| "_")\* + name: `lc_letter` (`lc_letter` | "_")* lc_letter: "a"..."z" The first line says that a ``name`` is an ``lc_letter`` followed by a sequence Modified: doctools/trunk/Doc-26/reference/lexical_analysis.rst ============================================================================== --- doctools/trunk/Doc-26/reference/lexical_analysis.rst (original) +++ doctools/trunk/Doc-26/reference/lexical_analysis.rst Thu Aug 2 14:32:13 2007 @@ -323,8 +323,8 @@ definitions: .. productionlist:: - identifier: (`letter`\|"_") (`letter` \| `digit` \| "_")\* - letter: `lowercase` \| `uppercase` + identifier: (`letter`|"_") (`letter` | `digit` | "_")\* + letter: `lowercase` | `uppercase` lowercase: "a"..."z" uppercase: "A"..."Z" digit: "0"..."9" @@ -433,13 +433,13 @@ .. index:: single: ASCII@ASCII .. productionlist:: - stringliteral: [`stringprefix`](`shortstring` \| `longstring`) - stringprefix: "r" \| "u" \| "ur" \| "R" \| "U" \| "UR" \| "Ur" \| "uR" - shortstring: "'" `shortstringitem`\* "'" \| '"' `shortstringitem`\* '"' - longstring: ""'" `longstringitem`\* ""'" - : \| '"""' `longstringitem`\* '"""' - shortstringitem: `shortstringchar` \| `escapeseq` - longstringitem: `longstringchar` \| `escapeseq` + stringliteral: [`stringprefix`](`shortstring` | `longstring`) + stringprefix: "r" | "u" | "ur" | "R" | "U" | "UR" | "Ur" | "uR" + shortstring: "'" `shortstringitem`* "'" | '"' `shortstringitem`* '"' + longstring: ""'" `longstringitem`* ""'" + : | '"""' `longstringitem`* '"""' + shortstringitem: `shortstringchar` | `escapeseq` + longstringitem: `longstringchar` | `escapeseq` shortstringchar: <any source character except "\" or newline or the quote> longstringchar: <any source character except "\"> escapeseq: "\" <any ASCII character> @@ -640,14 +640,14 @@ definitions: .. productionlist:: - longinteger: `integer` ("l" \| "L") - integer: `decimalinteger` \| `octinteger` \| `hexinteger` - decimalinteger: `nonzerodigit` `digit`\* \| "0" - octinteger: "0" `octdigit`\ + - hexinteger: "0" ("x" \| "X") `hexdigit`\ + + longinteger: `integer` ("l" | "L") + integer: `decimalinteger` | `octinteger` | `hexinteger` + decimalinteger: `nonzerodigit` `digit`* | "0" + octinteger: "0" `octdigit`+ + hexinteger: "0" ("x" | "X") `hexdigit`+ nonzerodigit: "1"..."9" octdigit: "0"..."7" - hexdigit: `digit` \| "a"..."f" \| "A"..."F" + hexdigit: `digit` | "a"..."f" | "A"..."F" Although both lower case ``'l'`` and upper case ``'L'`` are allowed as suffix for long integers, it is strongly recommended to always use ``'L'``, since the @@ -674,12 +674,12 @@ Floating point literals are described by the following lexical definitions: .. productionlist:: - floatnumber: `pointfloat` \| `exponentfloat` - pointfloat: [`intpart`] `fraction` \| `intpart` "." - exponentfloat: (`intpart` \| `pointfloat`) `exponent` - intpart: `digit`\ + - fraction: "." `digit`\ + - exponent: ("e" \| "E") ["+" \| "-"] `digit`\ + + floatnumber: `pointfloat` | `exponentfloat` + pointfloat: [`intpart`] `fraction` | `intpart` "." + exponentfloat: (`intpart` | `pointfloat`) `exponent` + intpart: `digit`+ + fraction: "." `digit`+ + exponent: ("e" | "E") ["+" | "-"] `digit`+ Note that the integer and exponent parts of floating point numbers can look like octal integers, but are interpreted using radix 10. For example, ``077e010`` is @@ -702,7 +702,7 @@ Imaginary literals are described by the following lexical definitions: .. productionlist:: - imagnumber: (`floatnumber` \| `intpart`) ("j" \| "J") + imagnumber: (`floatnumber` | `intpart`) ("j" | "J") An imaginary literal yields a complex number with a real part of 0.0. Complex numbers are represented as a pair of floating point numbers and have the same Modified: doctools/trunk/Doc-26/reference/simple_stmts.rst ============================================================================== --- doctools/trunk/Doc-26/reference/simple_stmts.rst (original) +++ doctools/trunk/Doc-26/reference/simple_stmts.rst Thu Aug 2 14:32:13 2007 @@ -13,20 +13,20 @@ .. productionlist:: simple_stmt: `expression_stmt` - : \| `assert_stmt` - : \| `assignment_stmt` - : \| `augmented_assignment_stmt` - : \| `pass_stmt` - : \| `del_stmt` - : \| `print_stmt` - : \| `return_stmt` - : \| `yield_stmt` - : \| `raise_stmt` - : \| `break_stmt` - : \| `continue_stmt` - : \| `import_stmt` - : \| `global_stmt` - : \| `exec_stmt` + : | `assert_stmt` + : | `assignment_stmt` + : | `augmented_assignment_stmt` + : | `pass_stmt` + : | `del_stmt` + : | `print_stmt` + : | `return_stmt` + : | `yield_stmt` + : | `raise_stmt` + : | `break_stmt` + : | `continue_stmt` + : | `import_stmt` + : | `global_stmt` + : | `exec_stmt` .. _exprstmts: @@ -124,14 +124,14 @@ attributes or items of mutable objects: .. productionlist:: - assignment_stmt: (`target_list` "=")+ (`expression_list` \| `yield_expression`) - target_list: `target` ("," `target`)\* [","] + assignment_stmt: (`target_list` "=")+ (`expression_list` | `yield_expression`) + target_list: `target` ("," `target`)* [","] target: `identifier` - : \| "(" `target_list` ")" - : \| "[" `target_list` "]" - : \| `attributeref` - : \| `subscription` - : \| `slicing` + : | "(" `target_list` ")" + : | "[" `target_list` "]" + : | `attributeref` + : | `subscription` + : | `slicing` (See section :ref:`primaries` for the syntax definitions for the last three symbols.) @@ -272,9 +272,9 @@ operation and an assignment statement: .. productionlist:: - augmented_assignment_stmt: `target` `augop` (`expression_list` \| `yield_expression`) - augop: "+=" \| "-=" \| "\*=" \| "/=" \| "%=" \| "\*\*=" - : \| ">>=" \| "<<=" \| "&=" \| "^=" \| "\|=" + augmented_assignment_stmt: `target` `augop` (`expression_list` | `yield_expression`) + augop: "+=" | "-=" | "*=" | "/=" | "%=" | "**=" + : | ">>=" | "<<=" | "&=" | "^=" | "|=" (See section :ref:`primaries` for the syntax definitions for the last three symbols.) @@ -378,8 +378,8 @@ .. index:: statement: print .. productionlist:: - print_stmt: "print" ([`expression` ("," `expression`)\* [","] - : \| ">>" `expression` [("," `expression`)+ [","]) + print_stmt: "print" ([`expression` ("," `expression`)* [","] + : | ">>" `expression` [("," `expression`)+ [","]) :keyword:`print` evaluates each expression in turn and writes the resulting object to standard output (see below). If an object is not a string, it is @@ -645,14 +645,14 @@ keyword: from .. productionlist:: - import_stmt: "import" `module` ["as" `name`] ( "," `module` ["as" `name`] )\* - : \| "from" `relative_module` "import" `identifier` ["as" `name`] - : ( "," `identifier` ["as" `name`] )\* - : \| "from" `relative_module` "import" "(" `identifier` ["as" `name`] - : ( "," `identifier` ["as" `name`] )\* [","] ")" - : \| "from" `module` "import" "\*" - module: (`identifier` ".")\* `identifier` - relative_module: "."\* `module` \| "."+ + import_stmt: "import" `module` ["as" `name`] ( "," `module` ["as" `name`] )* + : | "from" `relative_module` "import" `identifier` ["as" `name`] + : ( "," `identifier` ["as" `name`] )* + : | "from" `relative_module` "import" "(" `identifier` ["as" `name`] + : ( "," `identifier` ["as" `name`] )* [","] ")" + : | "from" `module` "import" "*" + module: (`identifier` ".")* `identifier` + relative_module: "."* `module` | "."+ name: `identifier` Import statements are executed in two steps: (1) find a module, and initialize @@ -781,9 +781,9 @@ .. productionlist:: * future_statement: "from" "__future__" "import" feature ["as" name] - : ("," feature ["as" name])\* - : \| "from" "__future__" "import" "(" feature ["as" name] - : ("," feature ["as" name])\* [","] ")" + : ("," feature ["as" name])* + : | "from" "__future__" "import" "(" feature ["as" name] + : ("," feature ["as" name])* [","] ")" feature: identifier name: identifier @@ -851,7 +851,7 @@ .. index:: statement: global .. productionlist:: - global_stmt: "global" `identifier` ("," `identifier`)\* + global_stmt: "global" `identifier` ("," `identifier`)* .. index:: triple: global; name; binding Modified: doctools/trunk/Doc-26/reference/toplevel_components.rst ============================================================================== --- doctools/trunk/Doc-26/reference/toplevel_components.rst (original) +++ doctools/trunk/Doc-26/reference/toplevel_components.rst Thu Aug 2 14:32:13 2007 @@ -66,7 +66,7 @@ All input read from non-interactive files has the same form: .. productionlist:: - file_input: (NEWLINE \| `statement`)\* + file_input: (NEWLINE | `statement`)* This syntax is used in the following situations: @@ -85,7 +85,7 @@ Input in interactive mode is parsed using the following grammar: .. productionlist:: - interactive_input: [`stmt_list`] NEWLINE \| `compound_stmt` NEWLINE + interactive_input: [`stmt_list`] NEWLINE | `compound_stmt` NEWLINE Note that a (top-level) compound statement must be followed by a blank line in interactive mode; this is needed to help the parser detect the end of the input. @@ -104,7 +104,7 @@ string argument to :func:`eval` must have the following form: .. productionlist:: - eval_input: `expression_list` NEWLINE\* + eval_input: `expression_list` NEWLINE* .. index:: builtin: input Modified: doctools/trunk/Doc-3k/TODO ============================================================================== --- doctools/trunk/Doc-3k/TODO (original) +++ doctools/trunk/Doc-3k/TODO Thu Aug 2 14:32:13 2007 @@ -3,14 +3,11 @@ * fix all references and links marked with `XXX` * adjust all literal include paths -* remove all non-literal includes * fix all duplicate labels and undefined label references * split very large files and add toctrees * integrate standalone HOWTOs * find out which files get "comments disabled" metadata -* double backslashes in production lists * add synopses for each module * write "About these documents" * finish "Documenting Python" * extend copyright.rst -* fix :file: and |version| in install Modified: doctools/trunk/Doc-3k/documenting/markup.rst ============================================================================== --- doctools/trunk/Doc-3k/documenting/markup.rst (original) +++ doctools/trunk/Doc-3k/documenting/markup.rst Thu Aug 2 14:32:13 2007 @@ -673,7 +673,7 @@ triple Likewise, ``triple: module; search; path`` is a shortcut that creates three index entries, which are ``module; search path``, ``search; path, module`` and - ``path; module search``. + ``path; module search``. module, keyword, operator, object, exception, statement, builtin These all create two index entries. For example, ``module: hashlib`` creates the entries ``module; hashlib`` and ``hashlib; module``. @@ -700,9 +700,10 @@ The definition can contain token names which are marked as interpreted text (e.g. ``sum ::= `integer` "+" `integer```) -- this generates cross-references - to the productions of these tokens. Note that vertical bars used to indicate - alternatives must be escaped with backslashes because otherwise they would - indicate a substitution reference to the reST parser. + to the productions of these tokens. + + Note that no further reST parsing is done in the production, so that you + don't have to escape ``*`` or ``|`` characters. .. XXX describe optional first parameter @@ -710,13 +711,13 @@ The following is an example taken from the Python Reference Manual:: .. productionlist:: - try_stmt: try1_stmt \| try2_stmt - try1_stmt: "try" ":" :token:`suite` - : ("except" [:token:`expression` ["," :token:`target`]] ":" :token:`suite`)+ - : ["else" ":" :token:`suite`] - : ["finally" ":" :token:`suite`] - try2_stmt: "try" ":" :token:`suite` - : "finally" ":" :token:`suite` + try_stmt: try1_stmt | try2_stmt + try1_stmt: "try" ":" `suite` + : ("except" [`expression` ["," `target`]] ":" `suite`)+ + : ["else" ":" `suite`] + : ["finally" ":" `suite`] + try2_stmt: "try" ":" `suite` + : "finally" ":" `suite` Substitutions Modified: doctools/trunk/Doc-3k/install/index.rst ============================================================================== --- doctools/trunk/Doc-3k/install/index.rst (original) +++ doctools/trunk/Doc-3k/install/index.rst Thu Aug 2 14:32:13 2007 @@ -246,19 +246,15 @@ Unix-based), it also depends on whether the module distribution being installed is pure Python or contains extensions ("non-pure"): -+-----------------+------------------------------------+--------------------------------------+-------+ -| Platform | Standard installation | Default value | Notes | -| | location | | | -+=================+====================================+======================================+=======+ -| Unix (pure) | :file:`{prefix}/lib/python|version | :file:`/usr/local/lib/python|version | \(1) | -| | |/site-packages` | |/site-packages` | | -+-----------------+------------------------------------+--------------------------------------+-------+ -| Unix (non-pure) | :file:`{exec- | :file:`/usr/local/lib/python|version | \(1) | -| | prefix}/lib/python|version | |/site-packages` | | -| | |/site-packages` | | | -+-----------------+------------------------------------+--------------------------------------+-------+ -| Windows | :file:`{prefix}` | :file:`C:\\Python` | \(2) | -+-----------------+------------------------------------+--------------------------------------+-------+ ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ +| Platform | Standard installation location | Default value | Notes | ++=================+=====================================================+==================================================+=======+ +| Unix (pure) | :file:`{prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1) | ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ +| Unix (non-pure) | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1) | ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ +| Windows | :file:`{prefix}` | :file:`C:\\Python` | \(2) | ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ Notes: @@ -346,17 +342,17 @@ The :option:`--home` option defines the installation base directory. Files are installed to the following directories under the installation base as follows: -+------------------------------+-----------------------------------+-----------------------------+ -| Type of file | Installation Directory | Override option | -+==============================+===================================+=============================+ -| pure module distribution | :file:`{home}`:file:`/lib/python` | :option:`--install-purelib` | -+------------------------------+-----------------------------------+-----------------------------+ -| non-pure module distribution | :file:`{home}`:file:`/lib/python` | :option:`--install-platlib` | -+------------------------------+-----------------------------------+-----------------------------+ -| scripts | :file:`{home}`:file:`/bin` | :option:`--install-scripts` | -+------------------------------+-----------------------------------+-----------------------------+ -| data | :file:`{home}`:file:`/share` | :option:`--install-data` | -+------------------------------+-----------------------------------+-----------------------------+ ++------------------------------+---------------------------+-----------------------------+ +| Type of file | Installation Directory | Override option | ++==============================+===========================+=============================+ +| pure module distribution | :file:`{home}/lib/python` | :option:`--install-purelib` | ++------------------------------+---------------------------+-----------------------------+ +| non-pure module distribution | :file:`{home}/lib/python` | :option:`--install-platlib` | ++------------------------------+---------------------------+-----------------------------+ +| scripts | :file:`{home}/bin` | :option:`--install-scripts` | ++------------------------------+---------------------------+-----------------------------+ +| data | :file:`{home}/share` | :option:`--install-data` | ++------------------------------+---------------------------+-----------------------------+ .. versionchanged:: 2.4 The :option:`--home` option used to be supported only on Unix. @@ -399,20 +395,17 @@ executables, etc.) If :option:`--exec-prefix` is not supplied, it defaults to :option:`--prefix`. Files are installed as follows: -+------------------------------+----------------------------------------+-----------------------------+ -| Type of file | Installation Directory | Override option | -+==============================+========================================+=============================+ -| pure module distribution | :file:`{prefix}`:file:`/lib/python2.{X | :option:`--install-purelib` | -| | }/site-packages` | | -+------------------------------+----------------------------------------+-----------------------------+ -| non-pure module distribution | :file:`{exec- | :option:`--install-platlib` | -| | prefix}`:file:`/lib/python2.{X | | -| | }/site-packages` | | -+------------------------------+----------------------------------------+-----------------------------+ -| scripts | :file:`{prefix}`:file:`/bin` | :option:`--install-scripts` | -+------------------------------+----------------------------------------+-----------------------------+ -| data | :file:`{prefix}`:file:`/share` | :option:`--install-data` | -+------------------------------+----------------------------------------+-----------------------------+ ++------------------------------+-----------------------------------------------------+-----------------------------+ +| Type of file | Installation Directory | Override option | ++==============================+=====================================================+=============================+ +| pure module distribution | :file:`{prefix}/lib/python{X.Y}/site-packages` | :option:`--install-purelib` | ++------------------------------+-----------------------------------------------------+-----------------------------+ +| non-pure module distribution | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :option:`--install-platlib` | ++------------------------------+-----------------------------------------------------+-----------------------------+ +| scripts | :file:`{prefix}/bin` | :option:`--install-scripts` | ++------------------------------+-----------------------------------------------------+-----------------------------+ +| data | :file:`{prefix}/share` | :option:`--install-data` | ++------------------------------+-----------------------------------------------------+-----------------------------+ There is no requirement that :option:`--prefix` or :option:`--exec-prefix` actually point to an alternate Python installation; if the directories listed @@ -455,17 +448,17 @@ :option:`--exec-prefix` option is not supported under Windows. Files are installed as follows: -+------------------------------+-----------------------------------+-----------------------------+ -| Type of file | Installation Directory | Override option | -+==============================+===================================+=============================+ -| pure module distribution | :file:`{prefix}`:file:`` | :option:`--install-purelib` | -+------------------------------+-----------------------------------+-----------------------------+ -| non-pure module distribution | :file:`{prefix}`:file:`` | :option:`--install-platlib` | -+------------------------------+-----------------------------------+-----------------------------+ -| scripts | :file:`{prefix}`:file:`\\Scripts` | :option:`--install-scripts` | -+------------------------------+-----------------------------------+-----------------------------+ -| data | :file:`{prefix}`:file:`\\Data` | :option:`--install-data` | -+------------------------------+-----------------------------------+-----------------------------+ ++------------------------------+---------------------------+-----------------------------+ +| Type of file | Installation Directory | Override option | ++==============================+===========================+=============================+ +| pure module distribution | :file:`{prefix}` | :option:`--install-purelib` | ++------------------------------+---------------------------+-----------------------------+ +| non-pure module distribution | :file:`{prefix}` | :option:`--install-platlib` | ++------------------------------+---------------------------+-----------------------------+ +| scripts | :file:`{prefix}\\Scripts` | :option:`--install-scripts` | ++------------------------------+---------------------------+-----------------------------+ +| data | :file:`{prefix}\\Data` | :option:`--install-data` | ++------------------------------+---------------------------+-----------------------------+ .. _custom-install: @@ -625,12 +618,12 @@ .. % $ <-- bow to font-lock The expected convention for locally installed packages is to put them in the -:file:`.../site-packages/` directory, but you may want to install Python modules -into some arbitrary directory. For example, your site may have a convention of -keeping all software related to the web server under :file:`/www`. Add-on -Python modules might then belong in :file:`/www/python`, and in order to import -them, this directory must be added to ``sys.path``. There are several different -ways to add the directory. +:file:`{...}/site-packages/` directory, but you may want to install Python +modules into some arbitrary directory. For example, your site may have a +convention of keeping all software related to the web server under :file:`/www`. +Add-on Python modules might then belong in :file:`/www/python`, and in order to +import them, this directory must be added to ``sys.path``. There are several +different ways to add the directory. The most convenient way is to add a path configuration file to a directory that's already on Python's path, usually to the :file:`.../site-packages/` @@ -921,7 +914,7 @@ The :file:`coff2omf` program comes with the Borland compiler. The file :file:`python25.lib` is in the :file:`Libs` directory of your Python -installation. If your extension uses other libraries (zlib,...) you have to +installation. If your extension uses other libraries (zlib, ...) you have to convert them too. The converted files have to reside in the same directories as the normal Modified: doctools/trunk/Doc-3k/reference/compound_stmts.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/compound_stmts.rst (original) +++ doctools/trunk/Doc-3k/reference/compound_stmts.rst Thu Aug 2 14:32:13 2007 @@ -44,15 +44,15 @@ .. productionlist:: compound_stmt: `if_stmt` - : \| `while_stmt` - : \| `for_stmt` - : \| `try_stmt` - : \| `with_stmt` - : \| `funcdef` - : \| `classdef` - suite: `stmt_list` NEWLINE \| NEWLINE INDENT `statement`\ + DEDENT - statement: `stmt_list` NEWLINE \| `compound_stmt` - stmt_list: `simple_stmt` (";" `simple_stmt`)\* [";"] + : | `while_stmt` + : | `for_stmt` + : | `try_stmt` + : | `with_stmt` + : | `funcdef` + : | `classdef` + suite: `stmt_list` NEWLINE | NEWLINE INDENT `statement`+ DEDENT + statement: `stmt_list` NEWLINE | `compound_stmt` + stmt_list: `simple_stmt` (";" `simple_stmt`)* [";"] .. index:: single: NEWLINE token @@ -80,7 +80,7 @@ .. productionlist:: if_stmt: "if" `expression` ":" `suite` - : ( "elif" `expression` ":" `suite` )\* + : ( "elif" `expression` ":" `suite` )* : ["else" ":" `suite`] .. index:: @@ -216,7 +216,7 @@ for a group of statements: .. productionlist:: - try_stmt: try1_stmt \| try2_stmt + try_stmt: try1_stmt | try2_stmt try1_stmt: "try" ":" `suite` : ("except" [`expression` ["," `target`]] ":" `suite`)+ : ["else" ":" `suite`] @@ -397,14 +397,14 @@ .. productionlist:: funcdef: [`decorators`] "def" `funcname` "(" [`parameter_list`] ")" ["->" `expression`]? ":" `suite` - decorators: `decorator`\ + + decorators: `decorator`+ decorator: "@" `dotted_name` ["(" [`argument_list` [","]] ")"] NEWLINE - dotted_name: `identifier` ("." `identifier`)\* - parameter_list: (`defparameter` ",")\* - : ( "\*" [`parameter`] ("," `defparameter`)\* - : [, "\*\*" `parameter`] - : \| "\*\*" `parameter` - : \| `defparameter` [","] ) + dotted_name: `identifier` ("." `identifier`)* + parameter_list: (`defparameter` ",")* + : ( "*" [`parameter`] ("," `defparameter`)* + : [, "**" `parameter`] + : | "**" `parameter` + : | `defparameter` [","] ) parameter: `identifier` [":" `expression`] defparameter: `parameter` ["=" `expression`] funcname: `identifier` Modified: doctools/trunk/Doc-3k/reference/expressions.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/expressions.rst (original) +++ doctools/trunk/Doc-3k/reference/expressions.rst Thu Aug 2 14:32:13 2007 @@ -63,10 +63,10 @@ atoms is: .. productionlist:: - atom: `identifier` \| `literal` \| `enclosure` - enclosure: `parenth_form` \| `list_display` - : \| `generator_expression` \| `dict_display` - : \| `string_conversion` \| `yield_atom` + atom: `identifier` | `literal` | `enclosure` + enclosure: `parenth_form` | `list_display` + : | `generator_expression` | `dict_display` + : | `string_conversion` | `yield_atom` .. _atom-identifiers: @@ -119,8 +119,8 @@ Python supports string literals and various numeric literals: .. productionlist:: - literal: `stringliteral` \| `integer` \| `longinteger` - : \| `floatnumber` \| `imagnumber` + literal: `stringliteral` | `integer` | `longinteger` + : | `floatnumber` | `imagnumber` Evaluation of a literal yields an object of the given type (string, integer, long integer, floating point number, complex number) with the given value. The @@ -183,11 +183,11 @@ brackets: .. productionlist:: - list_display: "[" [`expression_list` \| `list_comprehension`] "]" + list_display: "[" [`expression_list` | `list_comprehension`] "]" list_comprehension: `expression` `list_for` list_for: "for" `target_list` "in" `old_expression_list` [`list_iter`] old_expression_list: `old_expression` [("," `old_expression`)+ [","]] - list_iter: `list_for` \| `list_if` + list_iter: `list_for` | `list_if` list_if: "if" `old_expression` [`list_iter`] .. index:: @@ -219,7 +219,7 @@ .. productionlist:: generator_expression: "(" `expression` `genexpr_for` ")" genexpr_for: "for" `target_list` "in" `or_test` [`genexpr_iter`] - genexpr_iter: `genexpr_for` \| `genexpr_if` + genexpr_iter: `genexpr_for` | `genexpr_if` genexpr_if: "if" `old_expression` [`genexpr_iter`] .. index:: object: generator @@ -262,7 +262,7 @@ .. productionlist:: dict_display: "{" [`key_datum_list`] "}" - key_datum_list: `key_datum` ("," `key_datum`)\* [","] + key_datum_list: `key_datum` ("," `key_datum`)* [","] key_datum: `expression` ":" `expression` .. index:: object: dictionary @@ -425,7 +425,7 @@ syntax is: .. productionlist:: - primary: `atom` \| `attributeref` \| `subscription` \| `slicing` \| `call` + primary: `atom` | `attributeref` | `subscription` | `slicing` | `call` .. _attribute-references: @@ -517,12 +517,12 @@ :keyword:`del` statements. The syntax for a slicing: .. productionlist:: - slicing: `simple_slicing` \| `extended_slicing` + slicing: `simple_slicing` | `extended_slicing` simple_slicing: `primary` "[" `short_slice` "]" extended_slicing: `primary` "[" `slice_list` "]" - slice_list: `slice_item` ("," `slice_item`)\* [","] - slice_item: `expression` \| `proper_slice` \| `ellipsis` - proper_slice: `short_slice` \| `long_slice` + slice_list: `slice_item` ("," `slice_item`)* [","] + slice_item: `expression` | `proper_slice` | `ellipsis` + proper_slice: `short_slice` | `long_slice` short_slice: [`lower_bound`] ":" [`upper_bound`] long_slice: `short_slice` ":" [`stride`] lower_bound: `expression` @@ -581,16 +581,16 @@ .. productionlist:: call: `primary` "(" [`argument_list` [","] - : \| `expression` `genexpr_for`] ")" + : | `expression` `genexpr_for`] ")" argument_list: `positional_arguments` ["," `keyword_arguments`] - : ["," "\*" `expression`] - : ["," "\*\*" `expression`] - : \| `keyword_arguments` ["," "\*" `expression`] - : ["," "\*\*" `expression`] - : \| "\*" `expression` ["," "\*\*" `expression`] - : \| "\*\*" `expression` - positional_arguments: `expression` ("," `expression`)\* - keyword_arguments: `keyword_item` ("," `keyword_item`)\* + : ["," "*" `expression`] + : ["," "**" `expression`] + : | `keyword_arguments` ["," "*" `expression`] + : ["," "**" `expression`] + : | "*" `expression` ["," "**" `expression`] + : | "**" `expression` + positional_arguments: `expression` ("," `expression`)* + keyword_arguments: `keyword_item` ("," `keyword_item`)* keyword_item: `identifier` "=" `expression` A trailing comma may be present after the positional and keyword arguments but @@ -736,7 +736,7 @@ less tightly than unary operators on its right. The syntax is: .. productionlist:: - power: `primary` ["\*\*" `u_expr`] + power: `primary` ["**" `u_expr`] Thus, in an unparenthesized sequence of power and unary operators, the operators are evaluated from right to left (this does not constrain the evaluation order @@ -772,7 +772,7 @@ All unary arithmetic (and bit-wise) operations have the same priority: .. productionlist:: - u_expr: `power` \| "-" `u_expr` \| "+" `u_expr` \| "~" `u_expr` + u_expr: `power` | "-" `u_expr` | "+" `u_expr` | "~" `u_expr` .. index:: single: negation @@ -809,9 +809,9 @@ operators and one for additive operators: .. productionlist:: - m_expr: `u_expr` \| `m_expr` "\*" `u_expr` \| `m_expr` "//" `u_expr` \| `m_expr` "/" `u_expr` - : \| `m_expr` "%" `u_expr` - a_expr: `m_expr` \| `a_expr` "+" `m_expr` \| `a_expr` "-" `m_expr` + m_expr: `u_expr` | `m_expr` "*" `u_expr` | `m_expr` "//" `u_expr` | `m_expr` "/" `u_expr` + : | `m_expr` "%" `u_expr` + a_expr: `m_expr` | `a_expr` "+" `m_expr` | `a_expr` "-" `m_expr` .. index:: single: multiplication @@ -884,7 +884,7 @@ The shifting operations have lower priority than the arithmetic operations: .. productionlist:: - shift_expr: `a_expr` \| `shift_expr` ( "<<" \| ">>" ) `a_expr` + shift_expr: `a_expr` | `shift_expr` ( "<<" | ">>" ) `a_expr` These operators accept plain or long integers as arguments. The arguments are converted to a common type. They shift the first argument to the left or right @@ -909,9 +909,9 @@ Each of the three bitwise operations has a different priority level: .. productionlist:: - and_expr: `shift_expr` \| `and_expr` "&" `shift_expr` - xor_expr: `and_expr` \| `xor_expr` "^" `and_expr` - or_expr: `xor_expr` \| `or_expr` "\|" `xor_expr` + and_expr: `shift_expr` | `and_expr` "&" `shift_expr` + xor_expr: `and_expr` | `xor_expr` "^" `and_expr` + or_expr: `xor_expr` | `or_expr` "|" `xor_expr` .. index:: pair: bit-wise; and @@ -948,9 +948,9 @@ in mathematics: .. productionlist:: - comparison: `or_expr` ( `comp_operator` `or_expr` )\* - comp_operator: "<" \| ">" \| "==" \| ">=" \| "<=" \| "!=" - : \| "is" ["not"] \| ["not"] "in" + comparison: `or_expr` ( `comp_operator` `or_expr` )* + comp_operator: "<" | ">" | "==" | ">=" | "<=" | "!=" + : | "is" ["not"] | ["not"] "in" Comparisons yield boolean values: ``True`` or ``False``. @@ -1070,12 +1070,12 @@ Boolean operations have the lowest priority of all Python operations: .. productionlist:: - expression: `conditional_expression` \| `lambda_form` - old_expression: `or_test` \| `old_lambda_form` + expression: `conditional_expression` | `lambda_form` + old_expression: `or_test` | `old_lambda_form` conditional_expression: `or_test` ["if" `or_test` "else" `expression`] - or_test: `and_test` \| `or_test` "or" `and_test` - and_test: `not_test` \| `and_test` "and" `not_test` - not_test: `comparison` \| "not" `not_test` + or_test: `and_test` | `or_test` "or" `and_test` + and_test: `not_test` | `and_test` "and" `not_test` + not_test: `comparison` | "not" `not_test` In the context of Boolean operations, and also when expressions are used by control flow statements, the following values are interpreted as false: @@ -1149,7 +1149,7 @@ .. index:: pair: expression; list .. productionlist:: - expression_list: `expression` ( "," `expression` )\* [","] + expression_list: `expression` ( "," `expression` )* [","] .. index:: object: tuple @@ -1251,8 +1251,6 @@ +----------------------------------------------+-------------------------------------+ | ``{key:datum...}`` | Dictionary display | +----------------------------------------------+-------------------------------------+ -| ```expressions...``\ ` | String conversion | -+----------------------------------------------+-------------------------------------+ .. rubric:: Footnotes Modified: doctools/trunk/Doc-3k/reference/introduction.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/introduction.rst (original) +++ doctools/trunk/Doc-3k/reference/introduction.rst Thu Aug 2 14:32:13 2007 @@ -98,7 +98,7 @@ notation. This uses the following style of definition: .. productionlist:: * - name: `lc_letter` (`lc_letter` \| "_")\* + name: `lc_letter` (`lc_letter` | "_")* lc_letter: "a"..."z" The first line says that a ``name`` is an ``lc_letter`` followed by a sequence Modified: doctools/trunk/Doc-3k/reference/lexical_analysis.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/lexical_analysis.rst (original) +++ doctools/trunk/Doc-3k/reference/lexical_analysis.rst Thu Aug 2 14:32:13 2007 @@ -323,8 +323,8 @@ definitions: .. productionlist:: - identifier: (`letter`\|"_") (`letter` \| `digit` \| "_")\* - letter: `lowercase` \| `uppercase` + identifier: (`letter`|"_") (`letter` | `digit` | "_")\* + letter: `lowercase` | `uppercase` lowercase: "a"..."z" uppercase: "A"..."Z" digit: "0"..."9" @@ -432,13 +432,13 @@ .. index:: single: ASCII@ASCII .. productionlist:: - stringliteral: [`stringprefix`](`shortstring` \| `longstring`) - stringprefix: "r" \| "u" \| "ur" \| "R" \| "U" \| "UR" \| "Ur" \| "uR" - shortstring: "'" `shortstringitem`\* "'" \| '"' `shortstringitem`\* '"' - longstring: ""'" `longstringitem`\* ""'" - : \| '"""' `longstringitem`\* '"""' - shortstringitem: `shortstringchar` \| `escapeseq` - longstringitem: `longstringchar` \| `escapeseq` + stringliteral: [`stringprefix`](`shortstring` | `longstring`) + stringprefix: "r" | "u" | "ur" | "R" | "U" | "UR" | "Ur" | "uR" + shortstring: "'" `shortstringitem`* "'" | '"' `shortstringitem`* '"' + longstring: ""'" `longstringitem`* ""'" + : | '"""' `longstringitem`* '"""' + shortstringitem: `shortstringchar` | `escapeseq` + longstringitem: `longstringchar` | `escapeseq` shortstringchar: <any source character except "\" or newline or the quote> longstringchar: <any source character except "\"> escapeseq: "\" <any ASCII character> @@ -639,14 +639,14 @@ Integer literals are described by the following lexical definitions: .. productionlist:: - integer: `decimalinteger` \| `octinteger` \| `hexinteger` - decimalinteger: `nonzerodigit` `digit`\* \| "0"+ - octinteger: "0" ("o" \| "O") `octdigit`\ + - hexinteger: "0" ("x" \| "X") `hexdigit`\ + - bininteger: "0" ("b" \| "B") `bindigit`\ + + integer: `decimalinteger` | `octinteger` | `hexinteger` + decimalinteger: `nonzerodigit` `digit`* | "0"+ + octinteger: "0" ("o" | "O") `octdigit`+ + hexinteger: "0" ("x" | "X") `hexdigit`+ + bininteger: "0" ("b" | "B") `bindigit`+ nonzerodigit: "1"..."9" octdigit: "0"..."7" - hexdigit: `digit` \| "a"..."f" \| "A"..."F" + hexdigit: `digit` | "a"..."f" | "A"..."F" bindigit: "0"..."1" Plain integer literals that are above the largest representable plain integer @@ -673,12 +673,12 @@ Floating point literals are described by the following lexical definitions: .. productionlist:: - floatnumber: `pointfloat` \| `exponentfloat` - pointfloat: [`intpart`] `fraction` \| `intpart` "." - exponentfloat: (`intpart` \| `pointfloat`) `exponent` - intpart: `digit`\ + - fraction: "." `digit`\ + - exponent: ("e" \| "E") ["+" \| "-"] `digit`\ + + floatnumber: `pointfloat` | `exponentfloat` + pointfloat: [`intpart`] `fraction` | `intpart` "." + exponentfloat: (`intpart` | `pointfloat`) `exponent` + intpart: `digit`+ + fraction: "." `digit`+ + exponent: ("e" | "E") ["+" | "-"] `digit`+ Note that the integer and exponent parts are always interpreted using radix 10. For example, ``077e010`` is legal, and denotes the same number as ``77e10``. The @@ -700,7 +700,7 @@ Imaginary literals are described by the following lexical definitions: .. productionlist:: - imagnumber: (`floatnumber` \| `intpart`) ("j" \| "J") + imagnumber: (`floatnumber` | `intpart`) ("j" | "J") An imaginary literal yields a complex number with a real part of 0.0. Complex numbers are represented as a pair of floating point numbers and have the same Modified: doctools/trunk/Doc-3k/reference/simple_stmts.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/simple_stmts.rst (original) +++ doctools/trunk/Doc-3k/reference/simple_stmts.rst Thu Aug 2 14:32:13 2007 @@ -13,18 +13,18 @@ .. productionlist:: simple_stmt: `expression_stmt` - : \| `assert_stmt` - : \| `assignment_stmt` - : \| `augmented_assignment_stmt` - : \| `pass_stmt` - : \| `del_stmt` - : \| `return_stmt` - : \| `yield_stmt` - : \| `raise_stmt` - : \| `break_stmt` - : \| `continue_stmt` - : \| `import_stmt` - : \| `global_stmt` + : | `assert_stmt` + : | `assignment_stmt` + : | `augmented_assignment_stmt` + : | `pass_stmt` + : | `del_stmt` + : | `return_stmt` + : | `yield_stmt` + : | `raise_stmt` + : | `break_stmt` + : | `continue_stmt` + : | `import_stmt` + : | `global_stmt` .. _exprstmts: @@ -122,14 +122,14 @@ attributes or items of mutable objects: .. productionlist:: - assignment_stmt: (`target_list` "=")+ (`expression_list` \| `yield_expression`) - target_list: `target` ("," `target`)\* [","] + assignment_stmt: (`target_list` "=")+ (`expression_list` | `yield_expression`) + target_list: `target` ("," `target`)* [","] target: `identifier` - : \| "(" `target_list` ")" - : \| "[" `target_list` "]" - : \| `attributeref` - : \| `subscription` - : \| `slicing` + : | "(" `target_list` ")" + : | "[" `target_list` "]" + : | `attributeref` + : | `subscription` + : | `slicing` (See section :ref:`primaries` for the syntax definitions for the last three symbols.) @@ -270,9 +270,9 @@ operation and an assignment statement: .. productionlist:: - augmented_assignment_stmt: `target` `augop` (`expression_list` \| `yield_expression`) - augop: "+=" \| "-=" \| "\*=" \| "/=" \| "%=" \| "\*\*=" - : \| ">>=" \| "<<=" \| "&=" \| "^=" \| "\|=" + augmented_assignment_stmt: `target` `augop` (`expression_list` | `yield_expression`) + augop: "+=" | "-=" | "*=" | "/=" | "%=" | "**=" + : | ">>=" | "<<=" | "&=" | "^=" | "|=" (See section :ref:`primaries` for the syntax definitions for the last three symbols.) @@ -582,14 +582,14 @@ keyword: from .. productionlist:: - import_stmt: "import" `module` ["as" `name`] ( "," `module` ["as" `name`] )\* - : \| "from" `relative_module` "import" `identifier` ["as" `name`] - : ( "," `identifier` ["as" `name`] )\* - : \| "from" `relative_module` "import" "(" `identifier` ["as" `name`] - : ( "," `identifier` ["as" `name`] )\* [","] ")" - : \| "from" `module` "import" "\*" - module: (`identifier` ".")\* `identifier` - relative_module: "."\* `module` \| "."+ + import_stmt: "import" `module` ["as" `name`] ( "," `module` ["as" `name`] )* + : | "from" `relative_module` "import" `identifier` ["as" `name`] + : ( "," `identifier` ["as" `name`] )* + : | "from" `relative_module` "import" "(" `identifier` ["as" `name`] + : ( "," `identifier` ["as" `name`] )* [","] ")" + : | "from" `module` "import" "*" + module: (`identifier` ".")* `identifier` + relative_module: "."* `module` | "."+ name: `identifier` Import statements are executed in two steps: (1) find a module, and initialize @@ -718,9 +718,9 @@ .. productionlist:: * future_statement: "from" "__future__" "import" feature ["as" name] - : ("," feature ["as" name])\* - : \| "from" "__future__" "import" "(" feature ["as" name] - : ("," feature ["as" name])\* [","] ")" + : ("," feature ["as" name])* + : | "from" "__future__" "import" "(" feature ["as" name] + : ("," feature ["as" name])* [","] ")" feature: identifier name: identifier @@ -788,7 +788,7 @@ .. index:: statement: global .. productionlist:: - global_stmt: "global" `identifier` ("," `identifier`)\* + global_stmt: "global" `identifier` ("," `identifier`)* .. index:: triple: global; name; binding Modified: doctools/trunk/Doc-3k/reference/toplevel_components.rst ============================================================================== --- doctools/trunk/Doc-3k/reference/toplevel_components.rst (original) +++ doctools/trunk/Doc-3k/reference/toplevel_components.rst Thu Aug 2 14:32:13 2007 @@ -66,7 +66,7 @@ All input read from non-interactive files has the same form: .. productionlist:: - file_input: (NEWLINE \| `statement`)\* + file_input: (NEWLINE | `statement`)* This syntax is used in the following situations: @@ -85,7 +85,7 @@ Input in interactive mode is parsed using the following grammar: .. productionlist:: - interactive_input: [`stmt_list`] NEWLINE \| `compound_stmt` NEWLINE + interactive_input: [`stmt_list`] NEWLINE | `compound_stmt` NEWLINE Note that a (top-level) compound statement must be followed by a blank line in interactive mode; this is needed to help the parser detect the end of the input. @@ -104,7 +104,7 @@ string argument to :func:`eval` must have the following form: .. productionlist:: - eval_input: `expression_list` NEWLINE\* + eval_input: `expression_list` NEWLINE* .. index:: builtin: input

1 0

r56665 - doctools/trunk/sphinx/directives.py doctools/trunk/sphinx/roles.py
by georg.brandl Aug. 2, 2007

Aug. 2, 2007

Author: georg.brandl Date: Thu Aug 2 14:25:10 2007 New Revision: 56665 Modified: doctools/trunk/sphinx/directives.py doctools/trunk/sphinx/roles.py Log: Don't interpret markup in productionlists. Modified: doctools/trunk/sphinx/directives.py ============================================================================== --- doctools/trunk/sphinx/directives.py (original) +++ doctools/trunk/sphinx/directives.py Thu Aug 2 14:25:10 2007 @@ -397,6 +397,28 @@ # ------ production list (for the reference) --------------------------------------- +token_re = re.compile('`([a-z_]+)`') + +def token_xrefs(text, env): + retnodes = [] + pos = 0 + for m in token_re.finditer(text): + if m.start() > pos: + txt = text[pos:m.start()] + retnodes.append(nodes.Text(txt, txt)) + refnode = addnodes.pending_xref(m.group(1)) + refnode['reftype'] = 'token' + refnode['reftarget'] = m.group(1) + refnode['modname'] = env.currmodule + refnode['classname'] = env.currclass + refnode += nodes.literal(m.group(1), m.group(1), classes=['xref']) + retnodes.append(refnode) + pos = m.end() + if pos < len(text): + retnodes.append(nodes.Text(text[pos:], text[pos:])) + print retnodes + return retnodes + def productionlist_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): env = state.document.settings.env @@ -404,8 +426,6 @@ messages = [] i = 0 - # use token as the default role while in production list - roles._roles[''] = roles._role_registry['token'] for rule in arguments[0].split('\n'): if i == 0 and ':' not in rule: # production group @@ -423,11 +443,8 @@ subnode['ids'].append(idname) state.document.note_implicit_target(subnode, subnode) env.note_token(subnode['tokenname']) - inodes, imessages = state.inline_text(tokens, lineno+i) - subnode.extend(inodes) - messages.extend(imessages) + subnode.extend(token_xrefs(tokens, env)) node.append(subnode) - del roles._roles[''] return [node] + messages productionlist_directive.content = 0 Modified: doctools/trunk/sphinx/roles.py ============================================================================== --- doctools/trunk/sphinx/roles.py (original) +++ doctools/trunk/sphinx/roles.py Thu Aug 2 14:25:10 2007 @@ -95,9 +95,6 @@ def xfileref_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): env = inliner.document.settings.env text = utils.unescape(text) - # 'token' is the default role inside 'productionlist' directives - if typ == '': - typ = 'token' if typ in ('func', 'meth', 'cfunc') and \ env.config.get('add_function_parentheses', True): text += '()'

1 0

Jump to page: