IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Replace all previously inter-document links by :ref:s.

Browse Source
This commit is contained in:
Georg Brandl 2007-08-02 18:07:46 +00:00
parent e7d56ddf90
commit a9f6483547
99 changed files with 661 additions and 867 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
Doc-26/TODO
View File

@ -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

5
Doc-26/about.rst
View File

@ -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 @@ to help with the docs, so feel free to send a mail there!
See :ref:`reporting-bugs` for information how to report bugs in Python itself.
.. include:: ACKS
.. % include the ACKS file here so that it can be maintained separately
.. include:: ACKS

9
Doc-26/c-api/concrete.rst
View File

@ -2201,22 +2201,19 @@ Dictionary Objects
.. 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)

11
Doc-26/c-api/intro.rst
View File

@ -99,12 +99,11 @@ declared. The sole exception are the type objects; since these must never be
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:

30
Doc-26/c-api/newtypes.rst
View File

@ -610,17 +610,17 @@ type objects) *must* have the :attr:`ob_size` field.
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 @@ XXX
.. 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 @@ objects which may also be containers. Types which do not store references to
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

5
Doc-26/c-api/utilities.rst
View File

@ -370,6 +370,7 @@ upon unmarshalling. *Py_MARSHAL_VERSION* indicates the current file format
.. 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 @@ Parsing arguments and building values
=====================================
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

2
Doc-26/distutils/index.rst
View File

@ -4,6 +4,8 @@
Distributing Python Modules
###############################
:Authors: Greg Ward, Anthony Baxter
:Email: distutils-sig@python.org
:Release: |version|
:Date: |today|

4
Doc-26/distutils/introduction.rst
View File

@ -6,8 +6,8 @@ An Introduction to Distutils
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:

2
Doc-26/extending/building.rst
View File

@ -52,7 +52,7 @@ example above uses only a subset. Specifically, the example specifies meta-
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.

19
Doc-26/extending/extending.rst
View File

@ -117,8 +117,8 @@ 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 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 @@ with an exception object (leaving out the error checking for now)::
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 :cfunc:`PyArg_ParseTuple` function is declared as follows::
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 itself.
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 @@ that is exported, so it has to be learned only once.
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).

5
Doc-26/extending/newtypes.rst
View File

@ -1355,9 +1355,8 @@ Abstract Protocol Support
-------------------------
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

12
Doc-26/extending/windows.rst
View File

@ -36,13 +36,11 @@ A Cookbook Approach
===================
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

24
Doc-26/install/index.rst
View File

@ -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 @@ XXX: input{boilerplate} :XXX
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 @@ new goodies to their toolbox. You don't need to know Python to read this
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 @@ Notes:
(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 @@ Distutils (see section :ref:`inst-config-files`.)
.. [#] Then you have no POSIX emulation available, but you also don't need
:file:`cygwin1.dll`.

3
Doc-26/library/array.rst
View File

@ -112,8 +112,7 @@ The following data items and methods are also supported:
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()

6
Doc-26/library/ast.rst
View File

@ -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@v.loewis.de>

6
Doc-26/library/audioop.rst
View File

@ -191,11 +191,7 @@ The module defines the following variables and functions:
.. 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.

11
Doc-26/library/codecs.rst
View File

@ -1141,11 +1141,7 @@ the table.
.. 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 @@ functions can be used directly if desired.
: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

12
Doc-26/library/distutils.rst
View File

@ -13,23 +13,17 @@ additional modules into a Python installation. The new modules may be either
100%-pure Python, or may be extension modules written in C, or may be
collections of Python packages which include modules coded in both Python and C.
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.

5
Doc-26/library/exceptions.rst
View File

@ -1,3 +1,4 @@
.. _bltin-exceptions:
Built-in Exceptions
===================
@ -40,8 +41,8 @@ prevent user code from raising an inappropriate error.
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.

12
Doc-26/library/functions.rst
View File

@ -154,8 +154,7 @@ available. They are listed here in alphabetical order.
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 @@ available. They are listed here in alphabetical order.
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 @@ available. They are listed here in alphabetical order.
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 @@ available. They are listed here in alphabetical order.
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

4
Doc-26/library/objects.rst
View File

@ -22,8 +22,8 @@ The tables in this chapter document the priorities of operators by listing them
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

13
Doc-26/library/operator.rst
View File

@ -36,13 +36,12 @@ the rich comparison operators they support:
__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

2
Doc-26/library/parser.rst
View File

@ -32,7 +32,7 @@ presented.
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

3
Doc-26/library/pdb.rst
View File

@ -406,6 +406,5 @@ The events have the following meaning:
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`.

50
Doc-26/library/stdtypes.rst
View File

@ -26,10 +26,7 @@ Some operations are supported by several object types; in particular,
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 @@ a complex number.
.. 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 @@ and xrange objects.
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 Class Instances
.. _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 @@ There are really two flavors of function objects: built-in functions and user-
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 @@ explicitly set it on the underlying function object::
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 @@ attribute.
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 @@ It is written as ``None``.
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 @@ They are written as ``False`` and ``True``, respectively.
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 @@ types, where they are relevant. Some of these are not reported by the
.. 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.

4
Doc-26/library/warnings.rst
View File

@ -16,8 +16,8 @@ warrant raising an exception and terminating the program. For example, one
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

10
Doc-26/library/weakref.rst
View File

@ -65,14 +65,8 @@ support weak references but can add support through subclassing::
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])

4
Doc-26/library/webbrowser.rst
View File

@ -151,9 +151,7 @@ Notes:
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.

2
Doc-26/library/xml.etree.elementtree.rst
View File

@ -267,7 +267,7 @@ The following methods work on the element's children (subelements).
.. 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

6
Doc-26/library/xml.sax.handler.rst
View File

@ -207,7 +207,7 @@ events in the input document:
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 @@ events in the input document:
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 @@ events in the input document:
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

4
Doc-26/maclib/mac.rst
View File

@ -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`,

61
Doc-26/reference/datamodel.rst
View File

@ -60,8 +60,8 @@ are still reachable. (Implementation note: the current implementation uses a
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 @@ Files
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 @@ Basic customization
.. 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 @@ sequences, it should iterate through the values.
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 @@ used by directly invoking their methods.
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)

10
Doc-26/reference/expressions.rst
View File

@ -747,9 +747,8 @@ a built-in function or method:
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 @@ identities hold approximately where ``x/y`` is replaced by ``floor(x/y)`` or
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 @@ their suffixes::
expr3, expr4 = expr1, expr2
.. _summary:
.. _operator-summary:
Summary
=======

6
Doc-26/reference/introduction.rst
View File

@ -29,9 +29,9 @@ especially where the implementation imposes additional limitations. Therefore,
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:

6
Doc-26/reference/lexical_analysis.rst
View File

@ -390,9 +390,9 @@ characters:
.. 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

8
Doc-26/reference/simple_stmts.rst
View File

@ -760,9 +760,8 @@ the module search works from inside a package.]
.. 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 @@ Code compiled by an :keyword:`exec` statement or calls to the builtin functions
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

12
Doc-26/tutorial/controlflow.rst
View File

@ -393,12 +393,12 @@ calls. Here's an example that fails due to this restriction::
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, '?'

17
Doc-26/tutorial/datastructures.rst
View File

@ -47,8 +47,7 @@ objects:
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 @@ Tuples and Sequences
====================
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 @@ Here is a brief demonstration::
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

3
Doc-26/tutorial/errors.rst
View File

@ -71,8 +71,7 @@ happened, in the form of a stack traceback. In general it contains a stack
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:

10
Doc-26/tutorial/glossary.rst
View File

@ -118,9 +118,8 @@ __future__
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 @@ namespace
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

30
Doc-26/tutorial/inputoutput.rst
View File

@ -323,14 +323,13 @@ data types like lists, dictionaries, or class instances, things get a lot more
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 @@ for reading::
(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.

4
Doc-26/tutorial/interactive.rst
View File

@ -115,8 +115,8 @@ deletes the names it creates once they are no longer needed; this is done since
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

5
Doc-26/tutorial/interpreter.rst
View File

@ -182,9 +182,8 @@ line to define the source file encoding::
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

22
Doc-26/tutorial/modules.rst
View File

@ -215,9 +215,8 @@ Some tips for experts:
.. 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 @@ Standard Modules
.. 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:

128
Doc-26/tutorial/stdlib.rst
View File

@ -10,8 +10,8 @@ Brief Tour of the Standard Library
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 @@ aids for working with large modules like :mod:`os`::
>>> 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 @@ that is easier to use::
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 @@ Command Line Arguments
======================
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 @@ powerful and flexible command line processing is provided by the :mod:`optparse`
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 @@ The most direct way to terminate a script is to use ``sys.exit()``.
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 @@ they are easier to read and debug::
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 @@ the underlying C library functions for floating point math::
>>> 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 @@ Internet Access
===============
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 @@ urllib2.html) for retrieving data from urls and :mod:`smtplib` (XXX reference:
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 @@ Data Compression
================
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 @@ that answers those questions immediately.
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 @@ performance advantage::
>>> 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 @@ One approach for developing high quality software is to write tests for each
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 @@ sure the code remains true to the documentation::
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 @@ Batteries Included
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:`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` (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:`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` (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:`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.

113
Doc-26/tutorial/stdlib2.rst
View File

@ -13,19 +13,17 @@ programming needs. These modules rarely occur in small scripts.
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 @@ reveal data structure::
[['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 @@ paragraphs of text to fit a given screen width::
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 @@ separators::
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 @@ templates for XML files, plain text reports, and HTML web reports.
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 @@ dependent. Threads can be used to improve the responsiveness of applications
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 @@ variables, and semaphores.
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 @@ more readable, and more reliable.
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 @@ last reference to it has been eliminated.
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 @@ Many data structure needs can be met with the built-in list type. However,
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 @@ usual 16 bytes per entry for regular lists of python int objects::
>>> 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 @@ suited for implementing queues and breadth first tree searches::
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 @@ module with functions for manipulating sorted lists::
>>> 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 @@ repeatedly access the smallest element but do not want to run a full list sort::
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

12
Doc-26/tutorial/whatnow.rst
View File

@ -11,7 +11,7 @@ should you go to learn more?
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 @@ the set are:
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:

20
Doc-26/whatsnew/2.3.rst
View File

@ -30,10 +30,9 @@ enhanced modules is lengthy.
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 @@ complete list of changes, or look through the CVS logs for all the details.
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 @@ complete list of changes, or look through the CVS logs for all the details.
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 @@ instances. The largest missing feature is that there's no standard library
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 @@ The help message is automatically generated for you::
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.

7
Doc-26/whatsnew/2.4.rst
View File

@ -25,10 +25,9 @@ fixed between Python 2.3 and 2.4. Both figures are likely to be underestimates.
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.
.. % ======================================================================

4
Doc-26/whatsnew/2.6.rst
View File

@ -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:

1
Doc-3k/TODO
View File

@ -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

5
Doc-3k/about.rst
View File

@ -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 @@ to help with the docs, so feel free to send a mail there!
See :ref:`reporting-bugs` for information how to report bugs in Python itself.
.. include:: ACKS
.. % include the ACKS file here so that it can be maintained separately
.. include:: ACKS

9
Doc-3k/c-api/concrete.rst
View File

@ -2318,22 +2318,19 @@ Dictionary Objects
.. 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)

11
Doc-3k/c-api/intro.rst
View File

@ -99,12 +99,11 @@ declared. The sole exception are the type objects; since these must never be
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:

30
Doc-3k/c-api/newtypes.rst
View File

@ -610,17 +610,17 @@ type objects) *must* have the :attr:`ob_size` field.
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 @@ XXX
.. 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 @@ objects which may also be containers. Types which do not store references to
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

5
Doc-3k/c-api/utilities.rst
View File

@ -366,6 +366,7 @@ upon unmarshalling. *Py_MARSHAL_VERSION* indicates the current file format
.. 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 @@ Parsing arguments and building values
=====================================
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

2
Doc-3k/distutils/index.rst
View File

@ -4,6 +4,8 @@
Distributing Python Modules
###############################
:Authors: Greg Ward, Anthony Baxter
:Email: distutils-sig@python.org
:Release: |version|
:Date: |today|

4
Doc-3k/distutils/introduction.rst
View File

@ -6,8 +6,8 @@ An Introduction to Distutils
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:

2
Doc-3k/extending/building.rst
View File

@ -52,7 +52,7 @@ example above uses only a subset. Specifically, the example specifies meta-
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.

22
Doc-3k/extending/extending.rst
View File

@ -115,10 +115,9 @@ inside the interpreter; if this variable is *NULL* no exception has occurred. A
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 @@ with an exception object (leaving out the error checking for now)::
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 :cfunc:`PyArg_ParseTuple` function is declared as follows::
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 itself.
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 @@ that is exported, so it has to be learned only once.
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).

5
Doc-3k/extending/newtypes.rst
View File

@ -1355,9 +1355,8 @@ Abstract Protocol Support
-------------------------
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

12
Doc-3k/extending/windows.rst
View File

@ -36,13 +36,11 @@ A Cookbook Approach
===================
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

24
Doc-3k/install/index.rst
View File

@ -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 @@ XXX: input{boilerplate} :XXX
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 @@ new goodies to their toolbox. You don't need to know Python to read this
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 @@ Notes:
(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 @@ Distutils (see section :ref:`inst-config-files`.)
.. [#] Then you have no POSIX emulation available, but you also don't need
:file:`cygwin1.dll`.

3
Doc-3k/library/array.rst
View File

@ -112,8 +112,7 @@ The following data items and methods are also supported:
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()

6
Doc-3k/library/audioop.rst
View File

@ -191,11 +191,7 @@ The module defines the following variables and functions:
.. 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.

11
Doc-3k/library/codecs.rst
View File

@ -1157,11 +1157,7 @@ the table.
.. 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 @@ functions can be used directly if desired.
: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

12
Doc-3k/library/distutils.rst
View File

@ -13,23 +13,17 @@ additional modules into a Python installation. The new modules may be either
100%-pure Python, or may be extension modules written in C, or may be
collections of Python packages which include modules coded in both Python and C.
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.

5
Doc-3k/library/exceptions.rst
View File

@ -1,3 +1,4 @@
.. _bltin-exceptions:
Built-in Exceptions
===================
@ -40,8 +41,8 @@ prevent user code from raising an inappropriate error.
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.

12
Doc-3k/library/functions.rst
View File

@ -154,8 +154,7 @@ available. They are listed here in alphabetical order.
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 @@ available. They are listed here in alphabetical order.
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 @@ available. They are listed here in alphabetical order.
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 @@ available. They are listed here in alphabetical order.
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

4
Doc-3k/library/objects.rst
View File

@ -22,8 +22,8 @@ The tables in this chapter document the priorities of operators by listing them
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

13
Doc-3k/library/operator.rst
View File

@ -36,13 +36,12 @@ the rich comparison operators they support:
__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

2
Doc-3k/library/parser.rst
View File

@ -32,7 +32,7 @@ presented.
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

3
Doc-3k/library/pdb.rst
View File

@ -405,6 +405,5 @@ The events have the following meaning:
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`.

50
Doc-3k/library/stdtypes.rst
View File

@ -26,10 +26,7 @@ Some operations are supported by several object types; in particular,
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 @@ a complex number.
.. 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 @@ and range objects.
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 Class Instances
.. _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 @@ There are really two flavors of function objects: built-in functions and user-
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 @@ explicitly set it on the underlying function object::
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 @@ attribute.
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 @@ It is written as ``None``.
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 @@ They are written as ``False`` and ``True``, respectively.
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 @@ types, where they are relevant. Some of these are not reported by the
.. 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.

4
Doc-3k/library/warnings.rst
View File

@ -16,8 +16,8 @@ warrant raising an exception and terminating the program. For example, one
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

10
Doc-3k/library/weakref.rst
View File

@ -65,14 +65,8 @@ support weak references but can add support through subclassing::
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])

4
Doc-3k/library/webbrowser.rst
View File

@ -151,9 +151,7 @@ Notes:
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.

2
Doc-3k/library/xml.etree.elementtree.rst
View File

@ -267,7 +267,7 @@ The following methods work on the element's children (subelements).
.. 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

6
Doc-3k/library/xml.sax.handler.rst
View File

@ -207,7 +207,7 @@ events in the input document:
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 @@ events in the input document:
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 @@ events in the input document:
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

4
Doc-3k/maclib/mac.rst
View File

@ -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`,

61
Doc-3k/reference/datamodel.rst
View File

@ -60,8 +60,8 @@ are still reachable. (Implementation note: the current implementation uses a
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 @@ Files
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 @@ Basic customization
.. 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 @@ values.
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 @@ used by directly invoking their methods.
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)

10
Doc-3k/reference/expressions.rst
View File

@ -699,9 +699,8 @@ a built-in function or method:
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 @@ identities hold approximately where ``x/y`` is replaced by ``floor(x/y)`` or
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 @@ their suffixes::
expr3, expr4 = expr1, expr2
.. _summary:
.. _operator-summary:
Summary
=======

6
Doc-3k/reference/introduction.rst
View File

@ -29,9 +29,9 @@ especially where the implementation imposes additional limitations. Therefore,
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:

6
Doc-3k/reference/lexical_analysis.rst
View File

@ -389,9 +389,9 @@ characters:
.. 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

10
Doc-3k/reference/simple_stmts.rst
View File

@ -697,9 +697,8 @@ the module search works from inside a package.]
.. 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 @@ Code compiled by calls to the builtin functions :func:`exec`, :func:`compile`
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

12
Doc-3k/tutorial/controlflow.rst
View File

@ -405,12 +405,12 @@ calls. Here's an example that fails due to this restriction::
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, '?'

17
Doc-3k/tutorial/datastructures.rst
View File

@ -47,8 +47,7 @@ objects:
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 @@ Tuples and Sequences
====================
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 @@ Here is a brief demonstration::
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

3
Doc-3k/tutorial/errors.rst
View File

@ -71,8 +71,7 @@ happened, in the form of a stack traceback. In general it contains a stack
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:

11
Doc-3k/tutorial/glossary.rst
View File

@ -100,9 +100,9 @@ __future__
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 @@ namespace
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

30
Doc-3k/tutorial/inputoutput.rst
View File

@ -323,14 +323,13 @@ data types like lists, dictionaries, or class instances, things get a lot more
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 @@ for reading::
(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.

4
Doc-3k/tutorial/interactive.rst
View File

@ -115,8 +115,8 @@ deletes the names it creates once they are no longer needed; this is done since
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

5
Doc-3k/tutorial/interpreter.rst
View File

@ -182,9 +182,8 @@ line to define the source file encoding::
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

22
Doc-3k/tutorial/modules.rst
View File

@ -215,9 +215,8 @@ Some tips for experts:
.. 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 @@ Standard Modules
.. 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:

128
Doc-3k/tutorial/stdlib.rst
View File

@ -10,8 +10,8 @@ Brief Tour of the Standard Library
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 @@ aids for working with large modules like :mod:`os`::
>>> 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 @@ that is easier to use::
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 @@ Command Line Arguments
======================
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 @@ powerful and flexible command line processing is provided by the :mod:`optparse`
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 @@ The most direct way to terminate a script is to use ``sys.exit()``.
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 @@ they are easier to read and debug::
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 @@ the underlying C library functions for floating point math::
>>> 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 @@ Internet Access
===============
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 @@ urllib2.html) for retrieving data from urls and :mod:`smtplib` (XXX reference:
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 @@ Data Compression
================
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 @@ that answers those questions immediately.
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 @@ performance advantage::
>>> 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 @@ One approach for developing high quality software is to write tests for each
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 @@ sure the code remains true to the documentation::
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 @@ Batteries Included
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:`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` (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:`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` (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:`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.

113
Doc-3k/tutorial/stdlib2.rst
View File

@ -13,19 +13,17 @@ programming needs. These modules rarely occur in small scripts.
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 @@ reveal data structure::
[['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 @@ paragraphs of text to fit a given screen width::
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 @@ separators::
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 @@ templates for XML files, plain text reports, and HTML web reports.
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 @@ dependent. Threads can be used to improve the responsiveness of applications
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 @@ variables, and semaphores.
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 @@ more readable, and more reliable.
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 @@ last reference to it has been eliminated.
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 @@ Many data structure needs can be met with the built-in list type. However,
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 @@ usual 16 bytes per entry for regular lists of python int objects::
>>> 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 @@ suited for implementing queues and breadth first tree searches::
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 @@ module with functions for manipulating sorted lists::
>>> 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 @@ repeatedly access the smallest element but do not want to run a full list sort::
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

12
Doc-3k/tutorial/whatnow.rst
View File

@ -11,7 +11,7 @@ should you go to learn more?
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 @@ the set are:
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:

20
Doc-3k/whatsnew/2.3.rst
View File

@ -30,10 +30,9 @@ enhanced modules is lengthy.
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 @@ complete list of changes, or look through the CVS logs for all the details.
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 @@ complete list of changes, or look through the CVS logs for all the details.
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 @@ instances. The largest missing feature is that there's no standard library
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 @@ The help message is automatically generated for you::
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.

7
Doc-3k/whatsnew/2.4.rst
View File

@ -25,10 +25,9 @@ fixed between Python 2.3 and 2.4. Both figures are likely to be underestimates.
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.
.. % ======================================================================

4
Doc-3k/whatsnew/2.6.rst
View File

@ -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: