From 36ee11eabe40fca1b090d20d8730fa21215d36da 2016-11-18 16:26:44
From: Min RK <benjaminrk@gmail.com>
Date: 2016-11-18 16:26:44
Subject: [PATCH] comments about `*` for kw-only

---

diff --git a/IPython/core/display.py b/IPython/core/display.py
index d99715e..1d12060 100644
--- a/IPython/core/display.py
+++ b/IPython/core/display.py
@@ -79,6 +79,7 @@ def _display_mimetype(mimetype, objs, raw=False, metadata=None):
 # Main functions
 #-----------------------------------------------------------------------------
 
+# use * to indicate transient is keyword-only
 def publish_display_data(data, metadata=None, source=None, *, transient=None, **kwargs):
     """Publish data and metadata to all frontends.
 
@@ -114,7 +115,7 @@ def publish_display_data(data, metadata=None, source=None, *, transient=None, **
         to specify metadata about particular representations.
     source : str, deprecated
         Unused.
-    transient : dict
+    transient : dict, keyword-only
         A dictionary of transient data, such as display_id.
         """
     from IPython.core.interactiveshell import InteractiveShell
@@ -214,6 +215,7 @@ def display(*objs, include=None, exclude=None, metadata=None, transient=None, di
         return DisplayHandle(display_id)
 
 
+# use * for keyword-only display_id arg
 def update_display(obj, *, display_id, **kwargs):
     """Update an existing display by id
 
diff --git a/IPython/core/displaypub.py b/IPython/core/displaypub.py
index ff1d097..a591851 100644
--- a/IPython/core/displaypub.py
+++ b/IPython/core/displaypub.py
@@ -52,7 +52,8 @@ class DisplayPublisher(Configurable):
             if not isinstance(metadata, dict):
                 raise TypeError('metadata must be a dict, got: %r' % data)
 
-    def publish(self, data, metadata=None, source=None, **kwargs):
+    # use * to indicate transient, update are keyword-only
+    def publish(self, data, metadata=None, source=None, *, transient=None, update=False, **kwargs):
         """Publish data and metadata to all frontends.
 
         See the ``display_data`` message in the messaging documentation for
@@ -88,6 +89,13 @@ class DisplayPublisher(Configurable):
             the data itself.
         source : str, deprecated
             Unused.
+        transient: dict, keyword-only
+            A dictionary for transient data.
+            Data in this dictionary should not be persisted as part of saving this output.
+            Examples include 'display_id'.
+        update: bool, keyword-only, default: False
+            If True, only update existing outputs with the same display_id,
+            rather than creating a new output.
         """
 
         # The default is to simply write the plain text data using sys.stdout.