Use "impl-detail" directive where applicable.
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/functions.rst b/Doc/library/functions.rst
index cfb4154..ff7c4b6 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])
@@ -1384,14 +1386,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/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/math.rst b/Doc/library/math.rst
index d46014b..78a8a56 100644
--- a/Doc/library/math.rst
+++ b/Doc/library/math.rst
@@ -331,7 +331,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/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/stdtypes.rst b/Doc/library/stdtypes.rst
index b4f62ad..66de129 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
@@ -796,13 +798,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.
@@ -1629,10 +1633,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:
@@ -2006,20 +2013,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 b491c78..8264a39 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
@@ -830,12 +832,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