Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r75363 | georg.brandl | 2009-10-11 20:31:23 +0200 (So, 11 Okt 2009) | 1 line
Add the Python FAQ lists to the documentation. Copied from sandbox/faq. Many thanks to AMK for the preparation work.
........
r75365 | georg.brandl | 2009-10-11 22:16:16 +0200 (So, 11 Okt 2009) | 1 line
Fix broken links found by "make linkcheck". scipy.org seems to be done right now, so I could not verify links going there.
........
r75376 | benjamin.peterson | 2009-10-12 03:26:07 +0200 (Mo, 12 Okt 2009) | 1 line
platform we don't care about
........
r75392 | andrew.kuchling | 2009-10-13 18:11:49 +0200 (Di, 13 Okt 2009) | 1 line
Various link, textual, and markup fixes
........
r75394 | georg.brandl | 2009-10-13 20:10:59 +0200 (Di, 13 Okt 2009) | 1 line
Fix markup.
........
r75403 | georg.brandl | 2009-10-14 17:57:46 +0200 (Mi, 14 Okt 2009) | 1 line
#7126: os.environ changes *do* take effect in subprocesses started with os.system().
........
r75418 | georg.brandl | 2009-10-14 20:48:32 +0200 (Mi, 14 Okt 2009) | 1 line
#7116: str.join() takes an iterable.
........
r75484 | georg.brandl | 2009-10-18 09:58:12 +0200 (So, 18 Okt 2009) | 1 line
Fix missing word.
........
r75572 | benjamin.peterson | 2009-10-20 23:55:17 +0200 (Di, 20 Okt 2009) | 1 line
clarify buffer arg #7178
........
r75580 | georg.brandl | 2009-10-21 09:15:59 +0200 (Mi, 21 Okt 2009) | 1 line
#7170: fix explanation about non-weakrefable builtin types.
........
r75590 | benjamin.peterson | 2009-10-22 04:36:47 +0200 (Do, 22 Okt 2009) | 1 line
rewrite to be nice to other implementations
........
r75592 | georg.brandl | 2009-10-22 09:05:48 +0200 (Do, 22 Okt 2009) | 1 line
Fix punctuation.
........
r75594 | georg.brandl | 2009-10-22 09:56:02 +0200 (Do, 22 Okt 2009) | 1 line
Fix markup.
........
r75595 | georg.brandl | 2009-10-22 09:56:56 +0200 (Do, 22 Okt 2009) | 1 line
Fix duplicate target.
........
r75596 | georg.brandl | 2009-10-22 10:05:04 +0200 (Do, 22 Okt 2009) | 1 line
Add a new directive marking up implementation details and start using it.
........
r75600 | georg.brandl | 2009-10-22 13:01:46 +0200 (Do, 22 Okt 2009) | 1 line
Make it more robust.
........
r75602 | georg.brandl | 2009-10-22 13:28:06 +0200 (Do, 22 Okt 2009) | 1 line
Document new directive.
........
r75603 | georg.brandl | 2009-10-22 13:28:23 +0200 (Do, 22 Okt 2009) | 1 line
Allow short form with text as argument.
........
r75605 | georg.brandl | 2009-10-22 13:48:10 +0200 (Do, 22 Okt 2009) | 1 line
Use "impl-detail" directive where applicable.
........
r75606 | georg.brandl | 2009-10-22 17:00:06 +0200 (Do, 22 Okt 2009) | 1 line
#6324: membership test tries iteration via __iter__.
........
r75607 | georg.brandl | 2009-10-22 17:04:09 +0200 (Do, 22 Okt 2009) | 1 line
#7088: document new functions in signal as Unix-only.
........
r75610 | georg.brandl | 2009-10-22 17:27:24 +0200 (Do, 22 Okt 2009) | 1 line
Reorder __slots__ fine print and add a clarification.
........
r75611 | georg.brandl | 2009-10-22 17:42:32 +0200 (Do, 22 Okt 2009) | 1 line
#7035: improve docs of the various <method>_errors() functions, and give them docstrings.
........
r75612 | georg.brandl | 2009-10-22 17:52:15 +0200 (Do, 22 Okt 2009) | 1 line
#7156: document curses as Unix-only.
........
r75613 | georg.brandl | 2009-10-22 17:54:35 +0200 (Do, 22 Okt 2009) | 1 line
#6977: getopt does not support optional option arguments.
........
r75616 | georg.brandl | 2009-10-22 18:17:05 +0200 (Do, 22 Okt 2009) | 1 line
Add proper references.
........
r75617 | georg.brandl | 2009-10-22 18:20:55 +0200 (Do, 22 Okt 2009) | 1 line
Make printout margin important.
........
r75623 | georg.brandl | 2009-10-23 10:14:44 +0200 (Fr, 23 Okt 2009) | 1 line
#7188: fix optionxform() docs.
........
r75627 | fred.drake | 2009-10-23 15:04:51 +0200 (Fr, 23 Okt 2009) | 2 lines
add further note about what's passed to optionxform
........
r75647 | georg.brandl | 2009-10-24 12:04:19 +0200 (Sa, 24 Okt 2009) | 1 line
Fix markup.
........
diff --git a/Doc/library/__builtin__.rst b/Doc/library/__builtin__.rst
index b3e1e11..5c89c0c 100644
--- a/Doc/library/__builtin__.rst
+++ b/Doc/library/__builtin__.rst
@@ -33,9 +33,10 @@
# ...
-As an implementation detail, most modules have the name ``__builtins__`` (note
-the ``'s'``) made available as part of their globals. The value of
-``__builtins__`` is normally either this module or the value of this modules's
-:attr:`__dict__` attribute. Since this is an implementation detail, it may not
-be used by alternate implementations of Python.
+.. impl-detail::
+ Most modules have the name ``__builtins__`` (note the ``'s'``) made available
+ as part of their globals. The value of ``__builtins__`` is normally either
+ this module or the value of this modules's :attr:`__dict__` attribute. Since
+ this is an implementation detail, it may not be used by alternate
+ implementations of Python.
diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst
index 89d6610..ef486f7 100644
--- a/Doc/library/codecs.rst
+++ b/Doc/library/codecs.rst
@@ -54,7 +54,7 @@
*incrementalencoder* and *incrementaldecoder*: These have to be factory
functions providing the following interface:
- ``factory(errors='strict')``
+ ``factory(errors='strict')``
The factory functions must return objects providing the interfaces defined by
the base classes :class:`IncrementalEncoder` and :class:`IncrementalDecoder`,
@@ -63,20 +63,24 @@
*streamreader* and *streamwriter*: These have to be factory functions providing
the following interface:
- ``factory(stream, errors='strict')``
+ ``factory(stream, errors='strict')``
The factory functions must return objects providing the interfaces defined by
the base classes :class:`StreamWriter` and :class:`StreamReader`, respectively.
Stream codecs can maintain state.
- Possible values for errors are ``'strict'`` (raise an exception in case of an
- encoding error), ``'replace'`` (replace malformed data with a suitable
- replacement marker, such as ``'?'``), ``'ignore'`` (ignore malformed data and
- continue without further notice), ``'xmlcharrefreplace'`` (replace with the
- appropriate XML character reference (for encoding only)) and
- ``'backslashreplace'`` (replace with backslashed escape sequences (for encoding
- only)) as well as any other error handling name defined via
- :func:`register_error`.
+ Possible values for errors are
+
+ * ``'strict'``: raise an exception in case of an encoding error
+ * ``'replace'``: replace malformed data with a suitable replacement marker,
+ such as ``'?'`` or ``'\ufffd'``
+ * ``'ignore'``: ignore malformed data and continue without further notice
+ * ``'xmlcharrefreplace'``: replace with the appropriate XML character
+ reference (for encoding only)
+ * ``'backslashreplace'``: replace with backslashed escape sequences (for
+ encoding only
+
+ as well as any other error handling name defined via :func:`register_error`.
In case a search function cannot find a given encoding, it should return
``None``.
@@ -177,27 +181,33 @@
.. function:: strict_errors(exception)
- Implements the ``strict`` error handling.
+ Implements the ``strict`` error handling: each encoding or decoding error
+ raises a :exc:`UnicodeError`.
.. function:: replace_errors(exception)
- Implements the ``replace`` error handling.
+ Implements the ``replace`` error handling: malformed data is replaced with a
+ suitable replacement character such as ``'?'`` in bytestrings and
+ ``'\ufffd'`` in Unicode strings.
.. function:: ignore_errors(exception)
- Implements the ``ignore`` error handling.
+ Implements the ``ignore`` error handling: malformed data is ignored and
+ encoding or decoding is continued without further notice.
.. function:: xmlcharrefreplace_errors(exception)
- Implements the ``xmlcharrefreplace`` error handling.
+ Implements the ``xmlcharrefreplace`` error handling (for encoding only): the
+ unencodable character is replaced by an appropriate XML character reference.
.. function:: backslashreplace_errors(exception)
- Implements the ``backslashreplace`` error handling.
+ Implements the ``backslashreplace`` error handling (for encoding only): the
+ unencodable character is replaced by a backslashed escape sequence.
To simplify working with encoded files or stream, the module also defines these
utility functions:
diff --git a/Doc/library/configparser.rst b/Doc/library/configparser.rst
index c3b5b8f..878685c 100644
--- a/Doc/library/configparser.rst
+++ b/Doc/library/configparser.rst
@@ -317,12 +317,23 @@
.. method:: RawConfigParser.optionxform(option)
- Transforms the option name *option* as found in an input file or as passed in by
- client code to the form that should be used in the internal structures. The
- default implementation returns a lower-case version of *option*; subclasses may
- override this or client code can set an attribute of this name on instances to
- affect this behavior. Setting this to :func:`str`, for example, would make
- option names case sensitive.
+ Transforms the option name *option* as found in an input file or as passed in
+ by client code to the form that should be used in the internal structures.
+ The default implementation returns a lower-case version of *option*;
+ subclasses may override this or client code can set an attribute of this name
+ on instances to affect this behavior.
+
+ You don't necessarily need to subclass a ConfigParser to use this method, you
+ can also re-set it on an instance, to a function that takes a string
+ argument. Setting it to ``str``, for example, would make option names case
+ sensitive::
+
+ cfgparser = ConfigParser()
+ ...
+ cfgparser.optionxform = str
+
+ Note that when reading configuration files, whitespace around the
+ option names are stripped before :meth:`optionxform` is called.
.. _configparser-objects:
diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst
index fa66d1e..a2519f4 100644
--- a/Doc/library/curses.rst
+++ b/Doc/library/curses.rst
@@ -1,13 +1,13 @@
-
:mod:`curses` --- Terminal handling for character-cell displays
===============================================================
.. module:: curses
- :synopsis: An interface to the curses library, providing portable terminal handling.
+ :synopsis: An interface to the curses library, providing portable terminal
+ handling.
+ :platform: Unix
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
.. sectionauthor:: Eric Raymond <esr@thyrsus.com>
-
.. versionchanged:: 1.6
Added support for the ``ncurses`` library and converted to a package.
diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
index 7251479..54fa755 100644
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -235,7 +235,7 @@
| | (-*t1.days*, -*t1.seconds*, |
| | -*t1.microseconds*), and to *t1*\* -1. (1)(4) |
+--------------------------------+-----------------------------------------------+
-| ``abs(t)`` | equivalent to +*t* when ``t.days >= 0``, and |
+| ``abs(t)`` | equivalent to +\ *t* when ``t.days >= 0``, and|
| | to -*t* when ``t.days < 0``. (2) |
+--------------------------------+-----------------------------------------------+
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 6892c65..96eff1e 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -523,8 +523,10 @@
Return the "identity" of an object. This is an integer (or long integer) which
is guaranteed to be unique and constant for this object during its lifetime.
- Two objects with non-overlapping lifetimes may have the same :func:`id` value.
- (Implementation note: this is the address of the object.)
+ Two objects with non-overlapping lifetimes may have the same :func:`id`
+ value.
+
+ .. impl-detail:: This is the address of the object.
.. function:: input([prompt])
@@ -1377,14 +1379,15 @@
elements are never used (such as when the loop is usually terminated with
:keyword:`break`).
- .. note::
+ .. impl-detail::
- :func:`xrange` is intended to be simple and fast. Implementations may impose
- restrictions to achieve this. The C implementation of Python restricts all
- arguments to native C longs ("short" Python integers), and also requires that
- the number of elements fit in a native C long. If a larger range is needed,
- an alternate version can be crafted using the :mod:`itertools` module:
- ``islice(count(start, step), (stop-start+step-1)//step)``.
+ :func:`xrange` is intended to be simple and fast. Implementations may
+ impose restrictions to achieve this. The C implementation of Python
+ restricts all arguments to native C longs ("short" Python integers), and
+ also requires that the number of elements fit in a native C long. If a
+ larger range is needed, an alternate version can be crafted using the
+ :mod:`itertools` module: ``islice(count(start, step),
+ (stop-start+step-1)//step)``.
.. function:: zip([iterable, ...])
diff --git a/Doc/library/getopt.rst b/Doc/library/getopt.rst
index 2c0fad9..927953c 100644
--- a/Doc/library/getopt.rst
+++ b/Doc/library/getopt.rst
@@ -30,19 +30,20 @@
.. note::
- Unlike GNU :cfunc:`getopt`, after a non-option argument, all further arguments
- are considered also non-options. This is similar to the way non-GNU Unix systems
- work.
+ Unlike GNU :cfunc:`getopt`, after a non-option argument, all further
+ arguments are considered also non-options. This is similar to the way
+ non-GNU Unix systems work.
*long_options*, if specified, must be a list of strings with the names of the
- long options which should be supported. The leading ``'-``\ ``-'`` characters
- should not be included in the option name. Long options which require an
- argument should be followed by an equal sign (``'='``). To accept only long
- options, *options* should be an empty string. Long options on the command line
- can be recognized so long as they provide a prefix of the option name that
- matches exactly one of the accepted options. For example, if *long_options* is
- ``['foo', 'frob']``, the option :option:`--fo` will match as :option:`--foo`,
- but :option:`--f` will not match uniquely, so :exc:`GetoptError` will be raised.
+ long options which should be supported. The leading ``'-``\ ``-'``
+ characters should not be included in the option name. Long options which
+ require an argument should be followed by an equal sign (``'='``). Optional
+ arguments are not supported. To accept only long options, *options* should
+ be an empty string. Long options on the command line can be recognized so
+ long as they provide a prefix of the option name that matches exactly one of
+ the accepted options. For example, if *long_options* is ``['foo', 'frob']``,
+ the option :option:`--fo` will match as :option:`--foo`, but :option:`--f`
+ will not match uniquely, so :exc:`GetoptError` will be raised.
The return value consists of two elements: the first is a list of ``(option,
value)`` pairs; the second is the list of program arguments left after the
diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
index 3619235..d85ac60 100644
--- a/Doc/library/inspect.rst
+++ b/Doc/library/inspect.rst
@@ -353,9 +353,11 @@
Return true if the object is a getset descriptor.
- getsets are attributes defined in extension modules via ``PyGetSetDef``
- structures. For Python implementations without such types, this method will
- always return ``False``.
+ .. impl-detail::
+
+ getsets are attributes defined in extension modules via
+ :ctype:`PyGetSetDef` structures. For Python implementations without such
+ types, this method will always return ``False``.
.. versionadded:: 2.5
@@ -364,9 +366,11 @@
Return true if the object is a member descriptor.
- Member descriptors are attributes defined in extension modules via
- ``PyMemberDef`` structures. For Python implementations without such types,
- this method will always return ``False``.
+ .. impl-detail::
+
+ Member descriptors are attributes defined in extension modules via
+ :ctype:`PyMemberDef` structures. For Python implementations without such
+ types, this method will always return ``False``.
.. versionadded:: 2.5
@@ -567,10 +571,12 @@
Return the frame object for the caller's stack frame.
- This function relies on Python stack frame support in the interpreter, which
- isn't guaranteed to exist in all implementations of Python. If running in
- an implementation without Python stack frame support this function returns
- ``None``.
+ .. impl-detail::
+
+ This function relies on Python stack frame support in the interpreter,
+ which isn't guaranteed to exist in all implementations of Python. If
+ running in an implementation without Python stack frame support this
+ function returns ``None``.
.. function:: stack([context])
diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index cf2f0bd..a72d3ed 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -96,8 +96,8 @@
*buffering* is an optional integer used to set the buffering policy. By
default full buffering is on. Pass 0 to switch buffering off (only allowed
- in binary mode), 1 to set line buffering, and an integer > 1 for full
- buffering.
+ in binary mode), 1 to set line buffering, and an integer > 1 to indicate the
+ size of the buffer.
*encoding* is the name of the encoding used to decode or encode the file.
This should only be used in text mode. The default encoding is platform
diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst
index 51cda8a..92f37cb 100644
--- a/Doc/library/mailbox.rst
+++ b/Doc/library/mailbox.rst
@@ -602,7 +602,7 @@
`nmh - Message Handling System <http://www.nongnu.org/nmh/>`_
Home page of :program:`nmh`, an updated version of the original :program:`mh`.
- `MH & nmh: Email for Users & Programmers <http://www.ics.uci.edu/~mh/book/>`_
+ `MH & nmh: Email for Users & Programmers <http://rand-mh.sourceforge.net/book/>`_
A GPL-licensed book on :program:`mh` and :program:`nmh`, with some information
on the mailbox format.
diff --git a/Doc/library/math.rst b/Doc/library/math.rst
index 96ea91a..2f5e128 100644
--- a/Doc/library/math.rst
+++ b/Doc/library/math.rst
@@ -321,7 +321,7 @@
The mathematical constant *e*.
-.. note::
+.. impl-detail::
The :mod:`math` module consists mostly of thin wrappers around the platform C
math library functions. Behavior in exceptional cases is loosely specified
diff --git a/Doc/library/msilib.rst b/Doc/library/msilib.rst
index 7dc3632..7d64de3 100644
--- a/Doc/library/msilib.rst
+++ b/Doc/library/msilib.rst
@@ -396,10 +396,10 @@
.. seealso::
- `Directory Table <http://msdn.microsoft.com/library/en-us/msi/setup/directory_table.asp>`_
- `File Table <http://msdn.microsoft.com/library/en-us/msi/setup/file_table.asp>`_
- `Component Table <http://msdn.microsoft.com/library/en-us/msi/setup/component_table.asp>`_
- `FeatureComponents Table <http://msdn.microsoft.com/library/en-us/msi/setup/featurecomponents_table.asp>`_
+ `Directory Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/directory_table.asp>`_
+ `File Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/file_table.asp>`_
+ `Component Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/component_table.asp>`_
+ `FeatureComponents Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/featurecomponents_table.asp>`_
.. _features:
@@ -424,7 +424,7 @@
.. seealso::
- `Feature Table <http://msdn.microsoft.com/library/en-us/msi/setup/feature_table.asp>`_
+ `Feature Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/feature_table.asp>`_
.. _msi-gui:
@@ -518,13 +518,13 @@
.. seealso::
- `Dialog Table <http://msdn.microsoft.com/library/en-us/msi/setup/dialog_table.asp>`_
- `Control Table <http://msdn.microsoft.com/library/en-us/msi/setup/control_table.asp>`_
- `Control Types <http://msdn.microsoft.com/library/en-us/msi/setup/controls.asp>`_
- `ControlCondition Table <http://msdn.microsoft.com/library/en-us/msi/setup/controlcondition_table.asp>`_
- `ControlEvent Table <http://msdn.microsoft.com/library/en-us/msi/setup/controlevent_table.asp>`_
- `EventMapping Table <http://msdn.microsoft.com/library/en-us/msi/setup/eventmapping_table.asp>`_
- `RadioButton Table <http://msdn.microsoft.com/library/en-us/msi/setup/radiobutton_table.asp>`_
+ `Dialog Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/dialog_table.asp>`_
+ `Control Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/control_table.asp>`_
+ `Control Types <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/controls.asp>`_
+ `ControlCondition Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/controlcondition_table.asp>`_
+ `ControlEvent Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/controlevent_table.asp>`_
+ `EventMapping Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/eventmapping_table.asp>`_
+ `RadioButton Table <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/radiobutton_table.asp>`_
.. _msi-tables:
@@ -553,5 +553,3 @@
This module contains definitions for the UIText and ActionText tables, for the
standard installer actions.
-
-
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 260b3b3..c8e47fc 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -1836,9 +1836,9 @@
.. function:: system(command)
Execute the command (a string) in a subshell. This is implemented by calling
- the Standard C function :cfunc:`system`, and has the same limitations. Changes
- to :data:`os.environ`, :data:`sys.stdin`, etc. are not reflected in the
- environment of the executed command.
+ the Standard C function :cfunc:`system`, and has the same limitations.
+ Changes to :data:`sys.stdin`, etc. are not reflected in the environment of the
+ executed command.
On Unix, the return value is the exit status of the process encoded in the
format specified for :func:`wait`. Note that POSIX does not specify the meaning
diff --git a/Doc/library/othergui.rst b/Doc/library/othergui.rst
index 9821173..d25645a 100644
--- a/Doc/library/othergui.rst
+++ b/Doc/library/othergui.rst
@@ -43,7 +43,7 @@
`PythonCAD <http://www.pythoncad.org/>`_. An online `tutorial
<http://www.pygtk.org/pygtk2tutorial/index.html>`_ is available.
- `PyQt <http://www.riverbankcomputing.co.uk/pyqt/index.php>`_
+ `PyQt <http://www.riverbankcomputing.co.uk/software/pyqt/>`_
PyQt is a :program:`sip`\ -wrapped binding to the Qt toolkit. Qt is an
extensive C++ GUI application development framework that is
available for Unix, Windows and Mac OS X. :program:`sip` is a tool
diff --git a/Doc/library/platform.rst b/Doc/library/platform.rst
index 98b7972..b98d992 100644
--- a/Doc/library/platform.rst
+++ b/Doc/library/platform.rst
@@ -98,7 +98,7 @@
.. function:: python_implementation()
Returns a string identifying the Python implementation. Possible return values
- are: 'CPython', 'IronPython', 'Jython'
+ are: 'CPython', 'IronPython', 'Jython'.
.. versionadded:: 2.6
diff --git a/Doc/library/pty.rst b/Doc/library/pty.rst
index 6579ef0..be879f2 100644
--- a/Doc/library/pty.rst
+++ b/Doc/library/pty.rst
@@ -3,8 +3,8 @@
========================================
.. module:: pty
- :platform: IRIX, Linux
- :synopsis: Pseudo-Terminal Handling for SGI and Linux.
+ :platform: Linux
+ :synopsis: Pseudo-Terminal Handling for Linux.
.. moduleauthor:: Steen Lumholt
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
@@ -14,8 +14,8 @@
controlling terminal programmatically.
Because pseudo-terminal handling is highly platform dependent, there is code to
-do it only for SGI and Linux. (The Linux code is supposed to work on other
-platforms, but hasn't been tested yet.)
+do it only for Linux. (The Linux code is supposed to work on other platforms,
+but hasn't been tested yet.)
The :mod:`pty` module defines the following functions:
@@ -32,8 +32,8 @@
.. function:: openpty()
Open a new pseudo-terminal pair, using :func:`os.openpty` if possible, or
- emulation code for SGI and generic Unix systems. Return a pair of file
- descriptors ``(master, slave)``, for the master and the slave end, respectively.
+ emulation code for generic Unix systems. Return a pair of file descriptors
+ ``(master, slave)``, for the master and the slave end, respectively.
.. function:: spawn(argv[, master_read[, stdin_read]])
diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst
index a7cf33d..84f08b3 100644
--- a/Doc/library/signal.rst
+++ b/Doc/library/signal.rst
@@ -157,8 +157,8 @@
The old values are returned as a tuple: (delay, interval).
- Attempting to pass an invalid interval timer will cause a
- :exc:`ItimerError`.
+ Attempting to pass an invalid interval timer will cause an
+ :exc:`ItimerError`. Availability: Unix.
.. versionadded:: 2.6
@@ -166,6 +166,7 @@
.. function:: getitimer(which)
Returns current value of a given interval timer specified by *which*.
+ Availability: Unix.
.. versionadded:: 2.6
@@ -186,14 +187,14 @@
.. function:: siginterrupt(signalnum, flag)
- Change system call restart behaviour: if *flag* is :const:`False`, system calls
- will be restarted when interrupted by signal *signalnum*, otherwise system calls will
- be interrupted. Returns nothing. Availability: Unix (see the man page
- :manpage:`siginterrupt(3)` for further information).
+ Change system call restart behaviour: if *flag* is :const:`False`, system
+ calls will be restarted when interrupted by signal *signalnum*, otherwise
+ system calls will be interrupted. Returns nothing. Availability: Unix (see
+ the man page :manpage:`siginterrupt(3)` for further information).
- Note that installing a signal handler with :func:`signal` will reset the restart
- behaviour to interruptible by implicitly calling :cfunc:`siginterrupt` with a true *flag*
- value for the given signal.
+ Note that installing a signal handler with :func:`signal` will reset the
+ restart behaviour to interruptible by implicitly calling
+ :cfunc:`siginterrupt` with a true *flag* value for the given signal.
.. versionadded:: 2.6
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 3666b92..0115fc1 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -195,9 +195,11 @@
: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
-comparison are ordered by their address.
+.. impl-detail::
+
+ Objects of different types except numbers are ordered by their type names;
+ objects of the same types that don't support proper comparison are ordered by
+ their address.
.. index::
operator: in
@@ -765,13 +767,15 @@
If *k* is ``None``, it is treated like ``1``.
(6)
- If *s* and *t* are both strings, some Python implementations such as CPython can
- usually perform an in-place optimization for assignments of the form ``s=s+t``
- or ``s+=t``. When applicable, this optimization makes quadratic run-time much
- less likely. This optimization is both version and implementation dependent.
- For performance sensitive code, it is preferable to use the :meth:`str.join`
- method which assures consistent linear concatenation performance across versions
- and implementations.
+ .. impl-detail::
+
+ If *s* and *t* are both strings, some Python implementations such as
+ CPython can usually perform an in-place optimization for assignments of
+ the form ``s = s + t`` or ``s += t``. When applicable, this optimization
+ makes quadratic run-time much less likely. This optimization is both
+ version and implementation dependent. For performance sensitive code, it
+ is preferable to use the :meth:`str.join` method which assures consistent
+ linear concatenation performance across versions and implementations.
.. versionchanged:: 2.4
Formerly, string concatenation never occurred in-place.
@@ -961,10 +965,11 @@
For 8-bit strings, this method is locale-dependent.
-.. method:: str.join(seq)
+.. method:: str.join(iterable)
- Return a string which is the concatenation of the strings in the sequence *seq*.
- The separator between elements is the string providing this method.
+ Return a string which is the concatenation of the strings in the
+ :term:`iterable` *iterable*. The separator between elements is the string
+ providing this method.
.. method:: str.ljust(width[, fillchar])
@@ -1593,10 +1598,13 @@
example, sort by department, then by salary grade).
(10)
- While a list is being sorted, the effect of attempting to mutate, or even
- inspect, the list is undefined. The C implementation of Python 2.3 and newer
- makes the list appear empty for the duration, and raises :exc:`ValueError` if it
- can detect that the list has been mutated during a sort.
+ .. impl-detail::
+
+ While a list is being sorted, the effect of attempting to mutate, or even
+ inspect, the list is undefined. The C implementation of Python 2.3 and
+ newer makes the list appear empty for the duration, and raises
+ :exc:`ValueError` if it can detect that the list has been mutated during a
+ sort.
.. _types-set:
@@ -1970,20 +1978,21 @@
Return a copy of the dictionary's list of ``(key, value)`` pairs.
- .. note::
+ .. impl-detail::
Keys and values are listed in an arbitrary order which is non-random,
varies across Python implementations, and depends on the dictionary's
- history of insertions and deletions. If :meth:`items`, :meth:`keys`,
- :meth:`values`, :meth:`iteritems`, :meth:`iterkeys`, and
- :meth:`itervalues` are called with no intervening modifications to the
- dictionary, the lists will directly correspond. This allows the
- creation of ``(value, key)`` pairs using :func:`zip`: ``pairs =
- zip(d.values(), d.keys())``. The same relationship holds for the
- :meth:`iterkeys` and :meth:`itervalues` methods: ``pairs =
- zip(d.itervalues(), d.iterkeys())`` provides the same value for
- ``pairs``. Another way to create the same list is ``pairs = [(v, k) for
- (k, v) in d.iteritems()]``.
+ history of insertions and deletions.
+
+ If :meth:`items`, :meth:`keys`, :meth:`values`, :meth:`iteritems`,
+ :meth:`iterkeys`, and :meth:`itervalues` are called with no intervening
+ modifications to the dictionary, the lists will directly correspond. This
+ allows the creation of ``(value, key)`` pairs using :func:`zip`: ``pairs =
+ zip(d.values(), d.keys())``. The same relationship holds for the
+ :meth:`iterkeys` and :meth:`itervalues` methods: ``pairs =
+ zip(d.itervalues(), d.iterkeys())`` provides the same value for
+ ``pairs``. Another way to create the same list is ``pairs = [(v, k) for
+ (k, v) in d.iteritems()]``.
.. method:: iteritems()
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index fd7a5c9..c7be131 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -417,8 +417,10 @@
that is deeper than the call stack, :exc:`ValueError` is raised. The default
for *depth* is zero, returning the frame at the top of the call stack.
- This function should be used for internal and specialized purposes only. It
- is not guaranteed to exist in all implementations of Python.
+ .. impl-detail::
+
+ This function should be used for internal and specialized purposes only.
+ It is not guaranteed to exist in all implementations of Python.
.. function:: getprofile()
@@ -440,12 +442,12 @@
Get the trace function as set by :func:`settrace`.
- .. note::
+ .. impl-detail::
The :func:`gettrace` function is intended only for implementing debuggers,
- profilers, coverage tools and the like. Its behavior is part of the
- implementation platform, rather than part of the language definition,
- and thus may not be available in all Python implementations.
+ profilers, coverage tools and the like. Its behavior is part of the
+ implementation platform, rather than part of the language definition, and
+ thus may not be available in all Python implementations.
.. versionadded:: 2.6
@@ -809,12 +811,12 @@
For more information on code and frame objects, refer to :ref:`types`.
- .. note::
+ .. impl-detail::
The :func:`settrace` function is intended only for implementing debuggers,
- profilers, coverage tools and the like. Its behavior is part of the
- implementation platform, rather than part of the language definition, and thus
- may not be available in all Python implementations.
+ profilers, coverage tools and the like. Its behavior is part of the
+ implementation platform, rather than part of the language definition, and
+ thus may not be available in all Python implementations.
.. function:: settscdump(on_flag)
diff --git a/Doc/library/types.rst b/Doc/library/types.rst
index 87fa0d5..637704b 100644
--- a/Doc/library/types.rst
+++ b/Doc/library/types.rst
@@ -241,8 +241,11 @@
as ``datetime.timedelta.days``. This type is used as descriptor for simple C
data members which use standard conversion functions; it has the same purpose
as the :class:`property` type, but for classes defined in extension modules.
- In other implementations of Python, this type may be identical to
- ``GetSetDescriptorType``.
+
+ .. impl-detail::
+
+ In other implementations of Python, this type may be identical to
+ ``GetSetDescriptorType``.
.. versionadded:: 2.5
diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst
index 5dcb030..d403c3c 100644
--- a/Doc/library/weakref.rst
+++ b/Doc/library/weakref.rst
@@ -1,4 +1,3 @@
-
:mod:`weakref` --- Weak references
==================================
@@ -73,6 +72,11 @@
obj = Dict(red=1, green=2, blue=3) # this object is weak referenceable
+.. impl-detail::
+
+ Other built-in types such as :class:`tuple` and :class:`long` do not support
+ weak references even when subclassed.
+
Extension types can easily be made to support weak references; see
:ref:`weakref-support`.