{
"__type": "IngestedDoc",
"__tag": 4010,
"_content": {},
"_ordered_sections": [],
"item_file": null,
"item_line": null,
"item_type": null,
"aliases": [],
"example_section_data": {
"__type": "Section",
"__tag": 4015,
"children": [],
"title": [],
"level": 0,
"target": null
},
"see_also": [],
"signature": null,
"references": null,
"qa": "config:integrating",
"arbitrary": [
{
"__type": "Section",
"__tag": 4015,
"children": [],
"title": [
{
"__type": "Text",
"__tag": 4046,
"value": "Integrating your objects with IPython"
}
],
"level": 0,
"target": "integrating"
},
{
"__type": "Section",
"__tag": 4015,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "To change the attributes displayed by tab-completing your object, define a "
},
{
"__type": "InlineCode",
"__tag": 4051,
"value": "__dir__(self)"
},
{
"__type": "Text",
"__tag": 4046,
"value": " method for it. For more details, see the documentation of the built-in "
},
{
"__type": "InlineRole",
"__tag": 4003,
"value": "dir",
"domain": "py",
"role": "func",
"inventory": "python"
}
]
},
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "You can also customise key completions for your objects, e.g. pressing tab after "
},
{
"__type": "InlineCode",
"__tag": 4051,
"value": "obj[\"a"
},
{
"__type": "Text",
"__tag": 4046,
"value": ". To do so, define a method "
},
{
"__type": "InlineCode",
"__tag": 4051,
"value": "_ipython_key_completions_()"
},
{
"__type": "Text",
"__tag": 4046,
"value": ", which returns a list of objects which are possible keys in a subscript expression "
},
{
"__type": "InlineCode",
"__tag": 4051,
"value": "obj[key]"
},
{
"__type": "Text",
"__tag": 4046,
"value": "."
}
]
},
{
"__type": "Admonition",
"__tag": 4056,
"kind": "versionadded",
"base_type": "neutral",
"children": [
{
"__type": "AdmonitionTitle",
"__tag": 4055,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "versionadded 5.0"
}
]
},
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "Custom key completions"
}
]
}
]
}
],
"title": [
{
"__type": "Text",
"__tag": 4046,
"value": "Tab completion"
}
],
"level": 1,
"target": null
},
{
"__type": "Section",
"__tag": 4015,
"children": [],
"title": [
{
"__type": "Text",
"__tag": 4046,
"value": "Rich display"
}
],
"level": 1,
"target": "integrating_rich_display"
},
{
"__type": "Section",
"__tag": 4015,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "IPython can display richer representations of objects. To do this, you can define "
},
{
"__type": "InlineCode",
"__tag": 4051,
"value": "_ipython_display_()"
},
{
"__type": "Text",
"__tag": 4046,
"value": ", or any of a number of "
},
{
"__type": "InlineCode",
"__tag": 4051,
"value": "_repr_*_()"
},
{
"__type": "Text",
"__tag": 4046,
"value": " methods. Note that these are surrounded by single, not double underscores."
}
]
},
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "Supported ``_repr_*_`` methods"
}
]
},
{
"__type": "Table",
"__tag": 4065,
"children": [
{
"__type": "TableRow",
"__tag": 4068,
"header": true,
"children": [
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "Format"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "REPL"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "Notebook"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "Qt Console"
}
]
}
]
}
]
},
{
"__type": "TableRow",
"__tag": 4068,
"header": false,
"children": [
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "InlineCode",
"__tag": 4051,
"value": "_repr_pretty_"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "yes"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "yes"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "yes"
}
]
}
]
}
]
},
{
"__type": "TableRow",
"__tag": 4068,
"header": false,
"children": [
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "InlineCode",
"__tag": 4051,
"value": "_repr_svg_"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "no"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "yes"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "yes"
}
]
}
]
}
]
},
{
"__type": "TableRow",
"__tag": 4068,
"header": false,
"children": [
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "InlineCode",
"__tag": 4051,
"value": "_repr_png_"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "no"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "yes"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "yes"
}
]
}
]
}
]
},
{
"__type": "TableRow",
"__tag": 4068,
"header": false,
"children": [
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "InlineCode",
"__tag": 4051,
"value": "_repr_jpeg_"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "no"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "yes"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "yes"
}
]
}
]
}
]
},
{
"__type": "TableRow",
"__tag": 4068,
"header": false,
"children": [
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "InlineCode",
"__tag": 4051,
"value": "_repr_html_"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "no"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "yes"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "no"
}
]
}
]
}
]
},
{
"__type": "TableRow",
"__tag": 4068,
"header": false,
"children": [
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "InlineCode",
"__tag": 4051,
"value": "_repr_javascript_"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "no"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "yes"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "no"
}
]
}
]
}
]
},
{
"__type": "TableRow",
"__tag": 4068,
"header": false,
"children": [
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "InlineCode",
"__tag": 4051,
"value": "_repr_markdown_"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "no"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "yes"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "no"
}
]
}
]
}
]
},
{
"__type": "TableRow",
"__tag": 4068,
"header": false,
"children": [
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "InlineCode",
"__tag": 4051,
"value": "_repr_latex_"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "no"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "yes"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "no"
}
]
}
]
}
]
},
{
"__type": "TableRow",
"__tag": 4068,
"header": false,
"children": [
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "InlineCode",
"__tag": 4051,
"value": "_repr_mimebundle_"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "no"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "?"
}
]
}
]
},
{
"__type": "TableCell",
"__tag": 4069,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "?"
}
]
}
]
}
]
}
]
},
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "If the methods don't exist, the standard "
},
{
"__type": "InlineCode",
"__tag": 4051,
"value": "repr()"
},
{
"__type": "Text",
"__tag": 4046,
"value": " is used. If a method exists and returns "
},
{
"__type": "InlineRole",
"__tag": 4003,
"value": "None",
"domain": "py",
"role": "data",
"inventory": null
},
{
"__type": "Text",
"__tag": 4046,
"value": ", it is treated the same as if it does not exist. In general, "
},
{
"__type": "Emphasis",
"__tag": 4047,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "all"
}
]
},
{
"__type": "Text",
"__tag": 4046,
"value": " available formatters will be called when an object is displayed, and it is up to the UI to select which to display. A given formatter should not generally change its output based on what other formats are available - that should be handled at a different level, such as the "
},
{
"__type": "InlineRole",
"__tag": 4003,
"value": "~.DisplayFormatter",
"domain": null,
"role": "class",
"inventory": null
},
{
"__type": "Text",
"__tag": 4046,
"value": ", or configuration."
}
]
},
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "InlineCode",
"__tag": 4051,
"value": "_repr_*_"
},
{
"__type": "Text",
"__tag": 4046,
"value": " methods should "
},
{
"__type": "Emphasis",
"__tag": 4047,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "return"
}
]
},
{
"__type": "Text",
"__tag": 4046,
"value": " data of the expected format and have no side effects. For example, "
},
{
"__type": "InlineCode",
"__tag": 4051,
"value": "_repr_html_"
},
{
"__type": "Text",
"__tag": 4046,
"value": " should return HTML as a "
},
{
"__type": "InlineRole",
"__tag": 4003,
"value": "str",
"domain": null,
"role": null,
"inventory": null
},
{
"__type": "Text",
"__tag": 4046,
"value": " and "
},
{
"__type": "InlineCode",
"__tag": 4051,
"value": "_repr_png_"
},
{
"__type": "Text",
"__tag": 4046,
"value": " should return PNG data as "
},
{
"__type": "InlineRole",
"__tag": 4003,
"value": "bytes",
"domain": null,
"role": null,
"inventory": null
},
{
"__type": "Text",
"__tag": 4046,
"value": "."
}
]
},
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "If you wish to take control of display via your own side effects, use "
},
{
"__type": "InlineCode",
"__tag": 4051,
"value": "_ipython_display_()"
},
{
"__type": "Text",
"__tag": 4046,
"value": "."
}
]
},
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "For example "
}
]
},
{
"__type": "Code",
"__tag": 4050,
"value": "class Shout(object):\n def __init__(self, text):\n self.text = text\n\n def _repr_html_(self):\n return \"\" + self.text + \"
\"",
"execution_status": null,
"out": ""
}
],
"title": [
{
"__type": "Text",
"__tag": 4046,
"value": "Custom methods"
}
],
"level": 2,
"target": null
},
{
"__type": "Section",
"__tag": 4015,
"children": [],
"title": [
{
"__type": "Text",
"__tag": 4046,
"value": "Special methods"
}
],
"level": 3,
"target": null
},
{
"__type": "Section",
"__tag": 4015,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "To customize how your object is pretty-printed, add a "
},
{
"__type": "InlineCode",
"__tag": 4051,
"value": "_repr_pretty_"
},
{
"__type": "Text",
"__tag": 4046,
"value": " method to the class. The method should accept a pretty printer, and a boolean that indicates whether the printer detected a cycle. The method should act on the printer to produce your customized pretty output. Here is an example "
}
]
},
{
"__type": "Code",
"__tag": 4050,
"value": "class MyObject(object):\n\n def _repr_pretty_(self, p, cycle):\n if cycle:\n p.text('MyObject(...)')\n else:\n p.text('MyObject[...]')",
"execution_status": null,
"out": ""
},
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "For details on how to use the pretty printer, see "
},
{
"__type": "InlineRole",
"__tag": 4003,
"value": "IPython.lib.pretty",
"domain": "py",
"role": "mod",
"inventory": null
},
{
"__type": "Text",
"__tag": 4046,
"value": "."
}
]
}
],
"title": [
{
"__type": "Text",
"__tag": 4046,
"value": "Pretty printing"
}
],
"level": 4,
"target": null
},
{
"__type": "Section",
"__tag": 4015,
"children": [],
"title": [
{
"__type": "Text",
"__tag": 4046,
"value": "More powerful methods"
}
],
"level": 4,
"target": null
},
{
"__type": "Section",
"__tag": 4015,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "We often want to provide frontends with guidance on how to display the data. To support this, "
},
{
"__type": "InlineCode",
"__tag": 4051,
"value": "_repr_*_()"
},
{
"__type": "Text",
"__tag": 4046,
"value": " methods (except "
},
{
"__type": "InlineCode",
"__tag": 4051,
"value": "_repr_pretty_"
},
{
"__type": "Text",
"__tag": 4046,
"value": "?) can also return a "
},
{
"__type": "InlineCode",
"__tag": 4051,
"value": "(data, metadata)"
},
{
"__type": "Text",
"__tag": 4046,
"value": " tuple where "
},
{
"__type": "InlineCode",
"__tag": 4051,
"value": "metadata"
},
{
"__type": "Text",
"__tag": 4046,
"value": " is a dictionary containing arbitrary key-value pairs for the frontend to interpret. An example use case is "
},
{
"__type": "InlineCode",
"__tag": 4051,
"value": "_repr_jpeg_()"
},
{
"__type": "Text",
"__tag": 4046,
"value": ", which can be set to return a jpeg image and a "
},
{
"__type": "InlineCode",
"__tag": 4051,
"value": "{'height': 400, 'width': 600}"
},
{
"__type": "Text",
"__tag": 4046,
"value": " dictionary to inform the frontend how to size the image."
}
]
}
],
"title": [
{
"__type": "Text",
"__tag": 4046,
"value": "Metadata"
}
],
"level": 3,
"target": null
},
{
"__type": "Section",
"__tag": 4015,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "The user can also register formatters for types without modifying the class "
}
]
},
{
"__type": "Code",
"__tag": 4050,
"value": "from bar.baz import Foo\n\ndef foo_html(obj):\n return '' % obj.name\n\nhtml_formatter = get_ipython().display_formatter.formatters['text/html']\nhtml_formatter.for_type(Foo, foo_html)\n\n# Or register a type without importing it - this does the same as above:\nhtml_formatter.for_type_by_name('bar.baz', 'Foo', foo_html)",
"execution_status": null,
"out": ""
}
],
"title": [
{
"__type": "Text",
"__tag": 4046,
"value": "Formatters for third-party types"
}
],
"level": 2,
"target": "third_party_formatting"
},
{
"__type": "Section",
"__tag": 4015,
"children": [
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "Rarely, you might want to display a custom traceback when reporting an exception. To do this, define the custom traceback using "
},
{
"__type": "InlineRole",
"__tag": 4003,
"value": "_render_traceback_(self)",
"domain": null,
"role": null,
"inventory": null
},
{
"__type": "Text",
"__tag": 4046,
"value": " method which returns a list of strings, one string for each line of the traceback. For example, the "
},
{
"__type": "Link",
"__tag": 4049,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "ipyparallel"
}
],
"url": "https://ipyparallel.readthedocs.io/",
"title": ""
},
{
"__type": "Text",
"__tag": 4046,
"value": " a parallel computing framework for IPython, does this to display errors from multiple engines."
}
]
},
{
"__type": "Paragraph",
"__tag": 4045,
"children": [
{
"__type": "Text",
"__tag": 4046,
"value": "Please be conservative in using this feature; by replacing the default traceback you may hide important information from the user."
}
]
}
],
"title": [
{
"__type": "Text",
"__tag": 4046,
"value": "Custom exception tracebacks"
}
],
"level": 1,
"target": null
}
],
"local_refs": []
}