{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In Python, objects can declare their textual representation using the " }, { "__type": "InlineRole", "__tag": 4003, "value": "__repr__", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " method. IPython expands on this idea and allows objects to declare other, rich representations including:" } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "HTML" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "JSON" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "PNG" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "JPEG" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "SVG" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "LaTeX" } ] } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A single object can declare some or all of these representations; all are handled by IPython's display system." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The main idea of the first approach is that you have to implement special display methods when you define your class, one for each representation you want to use. Here is a list of the names of the special methods and the values they must return:" } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineRole", "__tag": 4003, "value": "_repr_html_", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ": return raw HTML as a string, or a tuple (see below)." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineRole", "__tag": 4003, "value": "_repr_json_", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ": return a JSONable dict, or a tuple (see below)." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineRole", "__tag": 4003, "value": "_repr_jpeg_", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ": return raw JPEG data, or a tuple (see below)." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineRole", "__tag": 4003, "value": "_repr_png_", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ": return raw PNG data, or a tuple (see below)." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineRole", "__tag": 4003, "value": "_repr_svg_", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ": return raw SVG data as a string, or a tuple (see below)." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineRole", "__tag": 4003, "value": "_repr_latex_", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ": return LaTeX commands in a string surrounded by \"$\"," } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "or a tuple (see below)." } ] } ] } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineRole", "__tag": 4003, "value": "_repr_mimebundle_", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ": return a full mimebundle containing the mapping" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "from all mimetypes to data. Use this for any mime-type not listed above." } ] } ] } ] } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The above functions may also return the object's metadata alonside the data. If the metadata is available, the functions will return a tuple containing the data and metadata, in that order. If there is no metadata available, then the functions will return the data only." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When you are directly writing your own classes, you can adapt them for display in IPython by following the above approach. But in practice, you often need to work with existing classes that you can't easily modify." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "You can refer to the documentation on integrating with the display system in order to register custom formatters for already existing types (" }, { "__type": "InlineRole", "__tag": 4003, "value": "integrating_rich_display", "domain": null, "role": "ref", "inventory": null }, { "__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.4 display available without import" } ] } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 6.1 display available without import" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Since IPython 5.4 and 6.1 " }, { "__type": "CrossRef", "__tag": 4002, "value": "display", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "IPython.display" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " is automatically made available to the user without import. If you are using display in a document that might be used in a pure python context or with older version of IPython, use the following import at the top of your file " } ] }, { "__type": "Code", "__tag": 4050, "value": "from IPython.display import display", "execution_status": null } ], "title": [], "level": 0, "target": null }, "Warns": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Raises": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Yields": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Methods": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Returns": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "", "annotation": "handle: DisplayHandle", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Returns a handle on updatable displays for use with " }, { "__type": "CrossRef", "__tag": 4002, "value": "update_display", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "IPython.core.display_functions:update_display" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ", if " }, { "__type": "ParamRef", "__tag": 4071, "name": "display_id" }, { "__type": "Text", "__tag": 4046, "value": " is given. Returns " }, { "__type": "InlineRole", "__tag": 4003, "value": "None", "domain": null, "role": "any", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " if no " }, { "__type": "ParamRef", "__tag": 4071, "name": "display_id" }, { "__type": "Text", "__tag": 4046, "value": " is given (default)." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Display a Python object in all frontends." } ] } ], "title": [], "level": 0, "target": null }, "Receives": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Warnings": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Attributes": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Parameters": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "*objs", "annotation": "object", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The Python objects to display." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "raw", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Are the objects to be displayed already mimetype-keyed dicts of raw display data, or Python objects that need to be formatted before display? [default: False]" } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "include", "annotation": "list, tuple or set, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A list of format type strings (MIME types) to include in the format data dict. If this is set " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "only" } ] }, { "__type": "Text", "__tag": 4046, "value": " the format types included in this list will be computed." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "exclude", "annotation": "list, tuple or set, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A list of format type strings (MIME types) to exclude in the format data dict. If this is set all format types will be computed, except for those included in this argument." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "metadata", "annotation": "dict, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A dictionary of metadata to associate with the output. mime-type keys in this dictionary will be associated with the individual representation formats, if they exist." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "transient", "annotation": "dict, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A dictionary of transient data to associate with the output. Data in this dict should not be persisted to files (e.g. notebooks)." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "display_id", "annotation": "str, bool optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Set an id for the display. This id can be used for updating this display area later via update_display. If given as " }, { "__type": "InlineRole", "__tag": 4003, "value": "True", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", generate a new " }, { "__type": "ParamRef", "__tag": 4071, "name": "display_id" } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "clear", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Should the output area be cleared before displaying anything? If True, this will wait for additional output before clearing. [default: False]" } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "**kwargs", "annotation": "additional keyword-args, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Additional keyword-arguments are passed through to the display publisher." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "By default all representations will be computed and sent to the frontends. Frontends can decide which representation is used and how." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In terminal IPython this will be similar to using " }, { "__type": "InlineRole", "__tag": 4003, "value": "print", "domain": null, "role": "func", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", for use in richer frontends see Jupyter notebook examples with rich display logic." } ] } ], "title": [], "level": 0, "target": null }, "Other Parameters": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null } }, "_ordered_sections": [ "Summary", "Extended Summary", "Parameters", "Attributes", "Methods", "Returns", "Yields", "Receives", "Other Parameters", "Raises", "Warns", "Warnings", "Notes" ], "item_file": "/IPython/core/display_functions.py", "item_line": 85, "item_type": "function", "aliases": [ "IPython.display.display" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "class Json(object):\n def __init__(self, json):\n self.json = json\n def _repr_pretty_(self, pp, cycle):\n import json\n pp.text(json.dumps(self.json, indent=2))\n def __repr__(self):\n return str(self.json)\n", "execution_status": "none" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "d = Json({1:2, 3: {4:5}})\n", "execution_status": "none" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "print(d)\n", "execution_status": "none" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "display(d)\n", "execution_status": "none" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "def int_formatter(integer, pp, cycle):\n pp.text('I'*integer)\n", "execution_status": "none" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "plain = get_ipython().display_formatter.formatters['text/plain']\nplain.for_type(int, int_formatter)\ndisplay(7-5)\n", "execution_status": "none" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "del plain.type_printers[int]\ndisplay(7-5)\n", "execution_status": "none" } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "update_display", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "IPython.core.display_functions:update_display" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "func" } ] } ], "type": null } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "objs", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "VAR_POSITIONAL", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "include", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "exclude", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "metadata", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "transient", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "display_id", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "raw", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "False" }, { "__type": "SigParam", "__tag": 4030, "name": "clear", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "False" }, { "__type": "SigParam", "__tag": 4030, "name": "kwargs", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "VAR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "display" }, "references": null, "qa": "IPython.core.display_functions:display", "arbitrary": [], "local_refs": [ "**kwargs", "*objs", "clear", "display_id", "exclude", "include", "metadata", "raw", "transient" ] }