Some documentations about custom formatters (#14579)

IPython/core/formatters.py

@@ -1,6 +1,61
 # -*- coding: utf-8 -*-
 """Display formatters.
 
+This module defines the base instances in order to implement custom
+formatters/mimetypes
+got objects:
+
+As we want to see internal IPython working we are going to use the following
+function to diaply objects instead of the normal print or display method:
+
+    >>> ip = get_ipython()
+    >>> ip.display_formatter.format(...)
+    ({'text/plain': 'Ellipsis'}, {})
+
+This return a tuple with the mimebumdle for the current object, and the
+associated metadata.
+
+
+We can now define our own formatter and register it:
+
+
+    >>> from IPython.core.formatters import BaseFormatter, FormatterABC
+
+
+    >>> class LLMFormatter(BaseFormatter):
+    ...
+    ...     format_type = 'x-vendor/llm'
+    ...     print_method = '_repr_llm_'
+    ...     _return_type = (dict, str)
+
+    >>> llm_formatter = LLMFormatter(parent=ip.display_formatter)
+
+    >>> ip.display_formatter.formatters[LLMFormatter.format_type] = llm_formatter
+
+Now any class that define `_repr_llm_` will return a x-vendor/llm as part of
+it's display data:
+
+    >>> class A:
+    ...
+    ...     def _repr_llm_(self, *kwargs):
+    ...         return 'This a A'
+    ...
+
+    >>> ip.display_formatter.format(A())
+    ({'text/plain': '<IPython.core.formatters.A at ...>', 'x-vendor/llm': 'This a A'}, {})
+
+As usual, you can register methods for third party types (see
+:ref:`third_party_formatting`)
+
+    >>> def llm_int(obj):
+    ...      return 'This is the integer %s, in between %s and %s'%(obj, obj-1, obj+1)
+
+    >>> llm_formatter.for_type(int, llm_int)
+
+    >>> ip.display_formatter.format(42)
+    ({'text/plain': '42', 'x-vendor/llm': 'This is the integer 42, in between 41 and 43'}, {})
+
+
 Inheritance diagram:
 
 .. inheritance-diagram:: IPython.core.formatters
@@ -39,7 +94,8 class DisplayFormatter(Configurable):
         You can use this to set a white-list for formats to display.
         
         Most users will not need to change this value.
-        """).tag(config=True)
+        """,
+    ).tag(config=True)
 
     @default('active_types')
     def _active_types_default(self):
@@ -278,12 +334,15 def _get_type(obj):
     return getattr(obj, '__class__', None) or type(obj)
 
 
-_raise_key_error = Sentinel('_raise_key_error', __name__, 
+_raise_key_error = Sentinel(
+    "_raise_key_error",
+    __name__,
 """
 Special value to raise a KeyError
 
 Raise KeyError in `BaseFormatter.pop` if passed as the default value to `pop`
-""")
+""",
+)
 
 
 class BaseFormatter(Configurable):
@@ -604,7 +663,7 class PlainTextFormatter(BaseFormatter):
         help="""Truncate large collections (lists, dicts, tuples, sets) to this size.
         
         Set to 0 to disable truncation.
-        """
+        """,
     ).tag(config=True)
     
     # Look for a _repr_pretty_ methods to use for pretty printing.

docs/source/config/integrating.rst

@@ -9,7 +9,7 Tab completion
 
 To change the attributes displayed by tab-completing your object, define a
 ``__dir__(self)`` method for it. For more details, see the documentation of the
-built-in `dir() function <http://docs.python.org/library/functions.html#dir>`_.
+built-in :external+python:py:func:`dir`
 
 You can also customise key completions for your objects, e.g. pressing tab after
 ``obj["a``. To do so, define a method ``_ipython_key_completions_()``, which
@@ -25,7 +25,7 Rich display
 ============
 
 Custom methods
-----------------------
+--------------
 
 IPython can display richer representations of objects.
 To do this, you can define ``_ipython_display_()``, or any of a number of
@@ -154,6 +154,8 to inform the frontend how to size the image.
 
 
 
+.. _third_party_formatting:
+
 Formatters for third-party types
 --------------------------------