mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Replace all previously inter-document links by :ref:s.
This commit is contained in:
parent
e7d56ddf90
commit
a9f6483547
@ -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
|
||||
|
@ -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
|
||||
|
@ -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)
|
||||
|
@ -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:
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
@ -4,6 +4,8 @@
|
||||
Distributing Python Modules
|
||||
###############################
|
||||
|
||||
:Authors: Greg Ward, Anthony Baxter
|
||||
:Email: distutils-sig@python.org
|
||||
:Release: |version|
|
||||
:Date: |today|
|
||||
|
||||
|
@ -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:
|
||||
|
@ -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.
|
||||
|
||||
|
@ -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).
|
||||
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
@ -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`.
|
||||
|
||||
|
@ -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()
|
||||
|
@ -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>
|
||||
|
||||
|
||||
|
@ -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.
|
||||
|
||||
|
@ -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
|
||||
|
@ -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.
|
||||
|
@ -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.
|
||||
|
||||
|
@ -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
|
||||
|
||||
|
@ -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
|
||||
|
||||
|
@ -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
|
||||
|
||||
|
@ -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
|
||||
|
@ -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`.
|
||||
|
||||
|
@ -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.
|
||||
|
@ -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
|
||||
|
@ -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])
|
||||
|
@ -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.
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
@ -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`,
|
||||
|
@ -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)
|
||||
|
@ -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
|
||||
=======
|
||||
|
@ -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:
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
@ -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, '?'
|
||||
|
@ -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
|
||||
|
@ -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:
|
||||
|
@ -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
|
||||
|
||||
|
@ -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.
|
||||
|
||||
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
@ -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:
|
||||
|
||||
|
@ -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.
|
||||
|
||||
|
||||
|
@ -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
|
||||
|
@ -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:
|
||||
|
||||
|
@ -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.
|
||||
|
@ -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.
|
||||
|
||||
.. % ======================================================================
|
||||
|
||||
|
@ -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,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
|
||||
|
@ -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
|
||||
|
@ -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)
|
||||
|
@ -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:
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
@ -4,6 +4,8 @@
|
||||
Distributing Python Modules
|
||||
###############################
|
||||
|
||||
:Authors: Greg Ward, Anthony Baxter
|
||||
:Email: distutils-sig@python.org
|
||||
:Release: |version|
|
||||
:Date: |today|
|
||||
|
||||
|
@ -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:
|
||||
|
@ -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.
|
||||
|
||||
|
@ -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).
|
||||
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
@ -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`.
|
||||
|
||||
|
@ -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()
|
||||
|
@ -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.
|
||||
|
||||
|
@ -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
|
||||
|
@ -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.
|
||||
|
@ -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.
|
||||
|
||||
|
@ -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
|
||||
|
||||
|
@ -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
|
||||
|
||||
|
@ -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
|
||||
|
||||
|
@ -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
|
||||
|
@ -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`.
|
||||
|
||||
|
@ -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.
|
||||
|
@ -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
|
||||
|
@ -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])
|
||||
|
@ -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.
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
@ -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`,
|
||||
|
@ -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)
|
||||
|
@ -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
|
||||
=======
|
||||
|
@ -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:
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
@ -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, '?'
|
||||
|
@ -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
|
||||
|
@ -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:
|
||||
|
@ -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
|
||||
|
||||
|
@ -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.
|
||||
|
||||
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
@ -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:
|
||||
|
||||
|
@ -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.
|
||||
|
||||
|
||||
|
@ -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
|
||||
|
@ -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:
|
||||
|
||||
|
@ -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.
|
||||
|
@ -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.
|
||||
|
||||
.. % ======================================================================
|
||||
|
||||
|
@ -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:
|
||||
|
Loading…
Reference in New Issue
Block a user