##// END OF EJS Templates
Fix example usage of BaseFormatter.for_type_by_name....
Dan Allan -
Show More
@@ -1,110 +1,110 b''
1 .. _integrating:
1 .. _integrating:
2
2
3 =====================================
3 =====================================
4 Integrating your objects with IPython
4 Integrating your objects with IPython
5 =====================================
5 =====================================
6
6
7 Tab completion
7 Tab completion
8 ==============
8 ==============
9
9
10 To change the attributes displayed by tab-completing your object, define a
10 To change the attributes displayed by tab-completing your object, define a
11 ``__dir__(self)`` method for it. For more details, see the documentation of the
11 ``__dir__(self)`` method for it. For more details, see the documentation of the
12 built-in `dir() function <http://docs.python.org/library/functions.html#dir>`_.
12 built-in `dir() function <http://docs.python.org/library/functions.html#dir>`_.
13
13
14 You can also customise key completions for your objects, e.g. pressing tab after
14 You can also customise key completions for your objects, e.g. pressing tab after
15 ``obj["a``. To do so, define a method ``_ipython_key_completions_()``, which
15 ``obj["a``. To do so, define a method ``_ipython_key_completions_()``, which
16 returns a list of objects which are possible keys in a subscript expression
16 returns a list of objects which are possible keys in a subscript expression
17 ``obj[key]``.
17 ``obj[key]``.
18
18
19 .. versionadded:: 5.0
19 .. versionadded:: 5.0
20 Custom key completions
20 Custom key completions
21
21
22 .. _integrating_rich_display:
22 .. _integrating_rich_display:
23
23
24 Rich display
24 Rich display
25 ============
25 ============
26
26
27 The notebook and the Qt console can display richer representations of objects.
27 The notebook and the Qt console can display richer representations of objects.
28 To use this, you can define any of a number of ``_repr_*_()`` methods. Note that
28 To use this, you can define any of a number of ``_repr_*_()`` methods. Note that
29 these are surrounded by single, not double underscores.
29 these are surrounded by single, not double underscores.
30
30
31 Both the notebook and the Qt console can display ``svg``, ``png`` and ``jpeg``
31 Both the notebook and the Qt console can display ``svg``, ``png`` and ``jpeg``
32 representations. The notebook can also display ``html``, ``javascript``,
32 representations. The notebook can also display ``html``, ``javascript``,
33 ``markdown`` and ``latex``. If the methods don't exist, or return ``None``, it
33 ``markdown`` and ``latex``. If the methods don't exist, or return ``None``, it
34 falls back to a standard ``repr()``.
34 falls back to a standard ``repr()``.
35
35
36 For example::
36 For example::
37
37
38 class Shout(object):
38 class Shout(object):
39 def __init__(self, text):
39 def __init__(self, text):
40 self.text = text
40 self.text = text
41
41
42 def _repr_html_(self):
42 def _repr_html_(self):
43 return "<h1>" + self.text + "</h1>"
43 return "<h1>" + self.text + "</h1>"
44
44
45 We often want to provide frontends with guidance on how to display the data. To
45 We often want to provide frontends with guidance on how to display the data. To
46 support this, ``_repr_*_()`` methods can also return a ``(data, metadata)``
46 support this, ``_repr_*_()`` methods can also return a ``(data, metadata)``
47 tuple where ``metadata`` is a dictionary containing arbitrary key-value pairs for
47 tuple where ``metadata`` is a dictionary containing arbitrary key-value pairs for
48 the frontend to interpret. An example use case is ``_repr_jpeg_()``, which can
48 the frontend to interpret. An example use case is ``_repr_jpeg_()``, which can
49 be set to return a jpeg image and a ``{'height': 400, 'width': 600}`` dictionary
49 be set to return a jpeg image and a ``{'height': 400, 'width': 600}`` dictionary
50 to inform the frontend how to size the image.
50 to inform the frontend how to size the image.
51
51
52 There are also two more powerful display methods:
52 There are also two more powerful display methods:
53
53
54 .. class:: MyObject
54 .. class:: MyObject
55
55
56 .. method:: _repr_mimebundle_(include=None, exclude=None)
56 .. method:: _repr_mimebundle_(include=None, exclude=None)
57
57
58 Should return a dictionary of multiple formats, keyed by mimetype, or a tuple
58 Should return a dictionary of multiple formats, keyed by mimetype, or a tuple
59 of two dictionaries: *data, metadata*. If this returns something, other
59 of two dictionaries: *data, metadata*. If this returns something, other
60 ``_repr_*_`` methods are ignored. The method should take keyword arguments
60 ``_repr_*_`` methods are ignored. The method should take keyword arguments
61 ``include`` and ``exclude``, though it is not required to respect them.
61 ``include`` and ``exclude``, though it is not required to respect them.
62
62
63 .. method:: _ipython_display_()
63 .. method:: _ipython_display_()
64
64
65 Displays the object as a side effect; the return value is ignored. If this
65 Displays the object as a side effect; the return value is ignored. If this
66 is defined, all other display methods are ignored.
66 is defined, all other display methods are ignored.
67
67
68 To customize how the REPL pretty-prints your object, add a `_repr_pretty_`
68 To customize how the REPL pretty-prints your object, add a `_repr_pretty_`
69 method to the class. The method should accept a pretty printer, and a boolean
69 method to the class. The method should accept a pretty printer, and a boolean
70 that indicates whether the printer detected a cycle. The method should act on
70 that indicates whether the printer detected a cycle. The method should act on
71 the printer to produce your customized pretty output. Here is an example::
71 the printer to produce your customized pretty output. Here is an example::
72
72
73 class MyObject(object):
73 class MyObject(object):
74
74
75 def _repr_pretty_(self, p, cycle):
75 def _repr_pretty_(self, p, cycle):
76 if cycle:
76 if cycle:
77 p.text('MyObject(...)')
77 p.text('MyObject(...)')
78 else:
78 else:
79 p.text('MyObject[...]')
79 p.text('MyObject[...]')
80
80
81 For details, see :py:mod:`IPython.lib.pretty`.
81 For details, see :py:mod:`IPython.lib.pretty`.
82
82
83 Formatters for third-party types
83 Formatters for third-party types
84 --------------------------------
84 --------------------------------
85
85
86 The user can also register formatters for types without modifying the class::
86 The user can also register formatters for types without modifying the class::
87
87
88 from bar import Foo
88 from bar.baz import Foo
89
89
90 def foo_html(obj):
90 def foo_html(obj):
91 return '<marquee>Foo object %s</marquee>' % obj.name
91 return '<marquee>Foo object %s</marquee>' % obj.name
92
92
93 html_formatter = get_ipython().display_formatter.formatters['text/html']
93 html_formatter = get_ipython().display_formatter.formatters['text/html']
94 html_formatter.for_type(Foo, foo_html)
94 html_formatter.for_type(Foo, foo_html)
95
95
96 # Or register a type without importing it - this does the same as above:
96 # Or register a type without importing it - this does the same as above:
97 html_formatter.for_type_by_name('bar.Foo', foo_html)
97 html_formatter.for_type_by_name('bar.baz', 'Foo', foo_html)
98
98
99 Custom exception tracebacks
99 Custom exception tracebacks
100 ===========================
100 ===========================
101
101
102 Rarely, you might want to display a custom traceback when reporting an
102 Rarely, you might want to display a custom traceback when reporting an
103 exception. To do this, define the custom traceback using
103 exception. To do this, define the custom traceback using
104 `_render_traceback_(self)` method which returns a list of strings, one string
104 `_render_traceback_(self)` method which returns a list of strings, one string
105 for each line of the traceback. For example, the `ipyparallel
105 for each line of the traceback. For example, the `ipyparallel
106 <http://ipyparallel.readthedocs.io/>`__ a parallel computing framework for
106 <http://ipyparallel.readthedocs.io/>`__ a parallel computing framework for
107 IPython, does this to display errors from multiple engines.
107 IPython, does this to display errors from multiple engines.
108
108
109 Please be conservative in using this feature; by replacing the default traceback
109 Please be conservative in using this feature; by replacing the default traceback
110 you may hide important information from the user.
110 you may hide important information from the user.
General Comments 0
You need to be logged in to leave comments. Login now