summaryrefslogtreecommitdiffstats
path: root/Doc/library/repr.rst
diff options
context:
space:
mode:
authorGeorg Brandl <georg@python.org>2007-08-15 14:28:22 (GMT)
committerGeorg Brandl <georg@python.org>2007-08-15 14:28:22 (GMT)
commit116aa62bf54a39697e25f21d6cf6799f7faa1349 (patch)
tree8db5729518ed4ca88e26f1e26cc8695151ca3eb3 /Doc/library/repr.rst
parent739c01d47b9118d04e5722333f0e6b4d0c8bdd9e (diff)
downloadcpython-116aa62bf54a39697e25f21d6cf6799f7faa1349.zip
cpython-116aa62bf54a39697e25f21d6cf6799f7faa1349.tar.gz
cpython-116aa62bf54a39697e25f21d6cf6799f7faa1349.tar.bz2
Move the 3k reST doc tree in place.
Diffstat (limited to 'Doc/library/repr.rst')
-rw-r--r--Doc/library/repr.rst136
1 files changed, 136 insertions, 0 deletions
diff --git a/Doc/library/repr.rst b/Doc/library/repr.rst
new file mode 100644
index 0000000..493e2b3
--- /dev/null
+++ b/Doc/library/repr.rst
@@ -0,0 +1,136 @@
+
+:mod:`repr` --- Alternate :func:`repr` implementation
+=====================================================
+
+.. module:: repr
+ :synopsis: Alternate repr() implementation with size limits.
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+
+
+The :mod:`repr` module provides a means for producing object representations
+with limits on the size of the resulting strings. This is used in the Python
+debugger and may be useful in other contexts as well.
+
+This module provides a class, an instance, and a function:
+
+
+.. class:: Repr()
+
+ Class which provides formatting services useful in implementing functions
+ similar to the built-in :func:`repr`; size limits for different object types
+ are added to avoid the generation of representations which are excessively long.
+
+
+.. data:: aRepr
+
+ This is an instance of :class:`Repr` which is used to provide the :func:`repr`
+ function described below. Changing the attributes of this object will affect
+ the size limits used by :func:`repr` and the Python debugger.
+
+
+.. function:: repr(obj)
+
+ This is the :meth:`repr` method of ``aRepr``. It returns a string similar to
+ that returned by the built-in function of the same name, but with limits on
+ most sizes.
+
+
+.. _repr-objects:
+
+Repr Objects
+------------
+
+:class:`Repr` instances provide several members which can be used to provide
+size limits for the representations of different object types, and methods
+which format specific object types.
+
+
+.. attribute:: Repr.maxlevel
+
+ Depth limit on the creation of recursive representations. The default is ``6``.
+
+
+.. attribute:: Repr.maxdict
+ Repr.maxlist
+ Repr.maxtuple
+ Repr.maxset
+ Repr.maxfrozenset
+ Repr.maxdeque
+ Repr.maxarray
+
+ Limits on the number of entries represented for the named object type. The
+ default is ``4`` for :attr:`maxdict`, ``5`` for :attr:`maxarray`, and ``6`` for
+ the others.
+
+ .. versionadded:: 2.4
+ :attr:`maxset`, :attr:`maxfrozenset`, and :attr:`set`.
+
+
+.. attribute:: Repr.maxlong
+
+ Maximum number of characters in the representation for a long integer. Digits
+ are dropped from the middle. The default is ``40``.
+
+
+.. attribute:: Repr.maxstring
+
+ Limit on the number of characters in the representation of the string. Note
+ that the "normal" representation of the string is used as the character source:
+ if escape sequences are needed in the representation, these may be mangled when
+ the representation is shortened. The default is ``30``.
+
+
+.. attribute:: Repr.maxother
+
+ This limit is used to control the size of object types for which no specific
+ formatting method is available on the :class:`Repr` object. It is applied in a
+ similar manner as :attr:`maxstring`. The default is ``20``.
+
+
+.. method:: Repr.repr(obj)
+
+ The equivalent to the built-in :func:`repr` that uses the formatting imposed by
+ the instance.
+
+
+.. method:: Repr.repr1(obj, level)
+
+ Recursive implementation used by :meth:`repr`. This uses the type of *obj* to
+ determine which formatting method to call, passing it *obj* and *level*. The
+ type-specific methods should call :meth:`repr1` to perform recursive formatting,
+ with ``level - 1`` for the value of *level* in the recursive call.
+
+
+.. method:: Repr.repr_TYPE(obj, level)
+ :noindex:
+
+ Formatting methods for specific types are implemented as methods with a name
+ based on the type name. In the method name, **TYPE** is replaced by
+ ``string.join(string.split(type(obj).__name__, '_'))``. Dispatch to these
+ methods is handled by :meth:`repr1`. Type-specific methods which need to
+ recursively format a value should call ``self.repr1(subobj, level - 1)``.
+
+
+.. _subclassing-reprs:
+
+Subclassing Repr Objects
+------------------------
+
+The use of dynamic dispatching by :meth:`Repr.repr1` allows subclasses of
+:class:`Repr` to add support for additional built-in object types or to modify
+the handling of types already supported. This example shows how special support
+for file objects could be added::
+
+ import repr
+ import sys
+
+ class MyRepr(repr.Repr):
+ def repr_file(self, obj, level):
+ if obj.name in ['<stdin>', '<stdout>', '<stderr>']:
+ return obj.name
+ else:
+ return `obj`
+
+ aRepr = MyRepr()
+ print aRepr.repr(sys.stdin) # prints '<stdin>'
+