[Python-checkins] r75605 - in python/trunk/Doc: library/__builtin__.rst library/functions.rst library/inspect.rst library/math.rst library/platform.rst library/stdtypes.rst library/sys.rst library/types.rst reference/datamodel.rst reference/executionmodel.rst reference/expressions.rst reference/simple_stmts.rst using/cmdline.rst
georg.brandl
python-checkins at python.org
Thu Oct 22 13:48:11 CEST 2009
Author: georg.brandl
Date: Thu Oct 22 13:48:10 2009
New Revision: 75605
Log:
Use "impl-detail" directive where applicable.
Modified:
python/trunk/Doc/library/__builtin__.rst
python/trunk/Doc/library/functions.rst
python/trunk/Doc/library/inspect.rst
python/trunk/Doc/library/math.rst
python/trunk/Doc/library/platform.rst
python/trunk/Doc/library/stdtypes.rst
python/trunk/Doc/library/sys.rst
python/trunk/Doc/library/types.rst
python/trunk/Doc/reference/datamodel.rst
python/trunk/Doc/reference/executionmodel.rst
python/trunk/Doc/reference/expressions.rst
python/trunk/Doc/reference/simple_stmts.rst
python/trunk/Doc/using/cmdline.rst
Modified: python/trunk/Doc/library/__builtin__.rst
==============================================================================
--- python/trunk/Doc/library/__builtin__.rst (original)
+++ python/trunk/Doc/library/__builtin__.rst Thu Oct 22 13:48:10 2009
@@ -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.
Modified: python/trunk/Doc/library/functions.rst
==============================================================================
--- python/trunk/Doc/library/functions.rst (original)
+++ python/trunk/Doc/library/functions.rst Thu Oct 22 13:48:10 2009
@@ -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, ...])
Modified: python/trunk/Doc/library/inspect.rst
==============================================================================
--- python/trunk/Doc/library/inspect.rst (original)
+++ python/trunk/Doc/library/inspect.rst Thu Oct 22 13:48:10 2009
@@ -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])
Modified: python/trunk/Doc/library/math.rst
==============================================================================
--- python/trunk/Doc/library/math.rst (original)
+++ python/trunk/Doc/library/math.rst Thu Oct 22 13:48:10 2009
@@ -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
Modified: python/trunk/Doc/library/platform.rst
==============================================================================
--- python/trunk/Doc/library/platform.rst (original)
+++ python/trunk/Doc/library/platform.rst Thu Oct 22 13:48:10 2009
@@ -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
Modified: python/trunk/Doc/library/stdtypes.rst
==============================================================================
--- python/trunk/Doc/library/stdtypes.rst (original)
+++ python/trunk/Doc/library/stdtypes.rst Thu Oct 22 13:48:10 2009
@@ -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()
Modified: python/trunk/Doc/library/sys.rst
==============================================================================
--- python/trunk/Doc/library/sys.rst (original)
+++ python/trunk/Doc/library/sys.rst Thu Oct 22 13:48:10 2009
@@ -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)
Modified: python/trunk/Doc/library/types.rst
==============================================================================
--- python/trunk/Doc/library/types.rst (original)
+++ python/trunk/Doc/library/types.rst Thu Oct 22 13:48:10 2009
@@ -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
Modified: python/trunk/Doc/reference/datamodel.rst
==============================================================================
--- python/trunk/Doc/reference/datamodel.rst (original)
+++ python/trunk/Doc/reference/datamodel.rst Thu Oct 22 13:48:10 2009
@@ -56,13 +56,16 @@
they may be garbage-collected. An implementation is allowed to postpone garbage
collection or omit it altogether --- it is a matter of implementation quality
how garbage collection is implemented, as long as no objects are collected that
-are still reachable. (Implementation note: CPython currently 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
-documentation of the :mod:`gc` module for information on controlling the
-collection of cyclic garbage. Other implementations act differently and CPython
-may change.)
+are still reachable.
+
+.. impl-detail::
+
+ CPython currently 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 documentation of the :mod:`gc`
+ module for information on controlling the collection of cyclic garbage.
+ Other implementations act differently and CPython may change.
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
Modified: python/trunk/Doc/reference/executionmodel.rst
==============================================================================
--- python/trunk/Doc/reference/executionmodel.rst (original)
+++ python/trunk/Doc/reference/executionmodel.rst Thu Oct 22 13:48:10 2009
@@ -128,7 +128,7 @@
itself. ``__builtins__`` can be set to a user-created dictionary to create a
weak form of restricted execution.
-.. note::
+.. impl-detail::
Users should not touch ``__builtins__``; it is strictly an implementation
detail. Users wanting to override values in the built-in namespace should
Modified: python/trunk/Doc/reference/expressions.rst
==============================================================================
--- python/trunk/Doc/reference/expressions.rst (original)
+++ python/trunk/Doc/reference/expressions.rst Thu Oct 22 13:48:10 2009
@@ -663,13 +663,13 @@
raised. Otherwise, the list of filled slots is used as the argument list for
the call.
-.. note::
+.. impl-detail::
- An implementation may provide built-in functions whose positional parameters do
- not have names, even if they are 'named' for the purpose of documentation, and
- which therefore cannot be supplied by keyword. In CPython, this is the case for
- functions implemented in C that use :cfunc:`PyArg_ParseTuple` to parse their
- arguments.
+ An implementation may provide built-in functions whose positional parameters
+ do not have names, even if they are 'named' for the purpose of documentation,
+ and which therefore cannot be supplied by keyword. In CPython, this is the
+ case for functions implemented in C that use :cfunc:`PyArg_ParseTuple` to
+ parse their arguments.
If there are more positional arguments than there are formal parameter slots, a
:exc:`TypeError` exception is raised, unless a formal parameter using the syntax
Modified: python/trunk/Doc/reference/simple_stmts.rst
==============================================================================
--- python/trunk/Doc/reference/simple_stmts.rst (original)
+++ python/trunk/Doc/reference/simple_stmts.rst Thu Oct 22 13:48:10 2009
@@ -219,9 +219,11 @@
the length of the assigned sequence, thus changing the length of the target
sequence, if the object allows it.
-(In the current implementation, the syntax for targets is taken to be the same
-as for expressions, and invalid syntax is rejected during the code generation
-phase, causing less detailed error messages.)
+.. impl-detail::
+
+ In the current implementation, the syntax for targets is taken to be the same
+ as for expressions, and invalid syntax is rejected during the code generation
+ phase, causing less detailed error messages.
WARNING: Although the definition of assignment implies that overlaps between the
left-hand side and the right-hand side are 'safe' (for example ``a, b = b, a``
@@ -946,9 +948,11 @@
parameters or in a :keyword:`for` loop control target, :keyword:`class`
definition, function definition, or :keyword:`import` statement.
-(The current implementation does not enforce the latter two restrictions, but
-programs should not abuse this freedom, as future implementations may enforce
-them or silently change the meaning of the program.)
+.. impl-detail::
+
+ The current implementation does not enforce the latter two restrictions, but
+ programs should not abuse this freedom, as future implementations may enforce
+ them or silently change the meaning of the program.
.. index::
statement: exec
Modified: python/trunk/Doc/using/cmdline.rst
==============================================================================
--- python/trunk/Doc/using/cmdline.rst (original)
+++ python/trunk/Doc/using/cmdline.rst Thu Oct 22 13:48:10 2009
@@ -8,7 +8,7 @@
The CPython interpreter scans the command line and the environment for various
settings.
-.. note::
+.. impl-detail::
Other implementations' command line schemes may differ. See
:ref:`implementations` for further resources.
More information about the Python-checkins
mailing list