Mass rename of jupyter-comm-layer related functions

The following changes are made:

    `jupyter-initialize-connection` -> `jupyter-comm-initialize`
    `jupyter-connect-client` -> `jupyter-comm-add-handler`
    `jupyter-disconnect-client` -> `jupyter-comm-remove-handler`
    `jupyter-comm-client-loop` -> `jupyter-comm-handler-loop`

* README.org: Do it.

* jupyter-channel-ioloop-comm: Do it.

* jupyter-client.el: Do it.

* jupyter-comm-layer.el: Do it.
(jupyter-comm-layer): Rename `clients` slot to `handlers`. Update all uses.

* jupyter-kernel-process-manager.el: Do it.

* jupyter-repl.el: Do it.

* jupyter-server.el: Do it.

* jupyter-zmq-channel-comm.el: Do it.

* test/jupyter-server-test.el: Do it.

* test/jupyter-test.el: Do it.

Author: nnicandro

README.org

@@ -842,14 +842,14 @@ Methods that require a message type as an argument such as
 For a =jupyter-kernel-client= to start communicating with a kernel, the
 following steps are taken:
 
-1. Initialize the connection using =jupyter-initialize-connection=
+1. Initialize the connection using =jupyter-comm-initialize=
 2. Start listening on the client's channels with =jupyter-start-channels=
 
 When starting a local kernel process, both steps are taken care of in
 =jupyter-start-new-kernel=.
 
 For remote kernels, you will have to manually supply the connection JSON file
-to =jupyter-initialize-connection= and start the kernel channels.
+to =jupyter-comm-initialize= and start the kernel channels.
 **** Sending messages
 
 Once a connection is initialized, messages can be sent to the kernel using the
@@ -880,7 +880,7 @@ user and sends it to the kernel.
 Represents a client connected to a Jupyter kernel.
 *** Initializing a connection
 
-=jupyter-initialize-connection= takes a client and a connection file as
+=jupyter-comm-initialize= takes a client and a connection file as
 arguments and configures the client to communicate with the kernel whose
 connection information is contained in the [[http://jupyter-client.readthedocs.io/en/stable/kernels.html#connection-files][connection file]].
 
@@ -889,11 +889,11 @@ After initializing a connection, to begin communicating with a kernel call
 
 #+BEGIN_SRC elisp
 (let ((client (jupyter-kernel-client)))
-  (jupyter-initialize-connection client "kernel1234.json")
+  (jupyter-comm-initialize client "kernel1234.json")
   (jupyter-start-channels client))
 #+END_SRC
 
-=jupyter-initialize-connection= is mainly useful when initializing a remote
+=jupyter-comm-initialize= is mainly useful when initializing a remote
 connection or connecting to an existing kernel. In order to start a new kernel
 on the =localhost= use =jupyter-start-new-kernel=
 

jupyter-channel-ioloop-comm.el

@@ -38,7 +38,7 @@
 ;;
 ;; Initializing the connection
 ;;
-;; The `jupyter-initialize-connection' method should be called before calling
+;; The `jupyter-comm-initialize' method should be called before calling
 ;; `jupyter-comm-start' and should be passed a `jupyter-session' object used to
 ;; initialize the `jupyter-channel-ioloop' object.
 
@@ -70,7 +70,7 @@
                         (jupyter-session-id (oref comm session))
                         9 nil nil "…")))
 
-(cl-defmethod jupyter-initialize-connection ((comm jupyter-channel-ioloop-comm)
+(cl-defmethod jupyter-comm-initialize ((comm jupyter-channel-ioloop-comm)
                                              (session jupyter-session))
   (cl-call-next-method)
   (let ((endpoints (jupyter-session-endpoints session)))

jupyter-client.el

@@ -294,7 +294,7 @@ CLIENT defaults to `jupyter-current-client'."
 
 (defun jupyter--connection-info (info-or-session)
   "Return the connection plist according to INFO-OR-SESSION.
-See `jupyter-initialize-connection'."
+See `jupyter-comm-initialize'."
   (cond
    ((jupyter-session-p info-or-session)
     (jupyter-session-conn-info info-or-session))
@@ -312,7 +312,7 @@ See `jupyter-initialize-connection'."
 
 ;; FIXME: This requires that CLIENT is communicating with a kernel using a
 ;; `jupyter-channel-ioloop-comm' object.
-(cl-defmethod jupyter-initialize-connection ((client jupyter-kernel-client) info-or-session)
+(cl-defmethod jupyter-comm-initialize ((client jupyter-kernel-client) info-or-session)
   "Initialize CLIENT with connection INFO-OR-SESSION.
 INFO-OR-SESSION can be a file name, a plist, or a
 `jupyter-session' object that will be used to initialize CLIENT's
@@ -348,7 +348,7 @@ http://jupyter-client.readthedocs.io/en/latest/kernels.html#connection-files."
               (jupyter-session
                :key (plist-get conn-info :key)
                :conn-info conn-info)))
-    (jupyter-initialize-connection
+    (jupyter-comm-initialize
      (oref client kcomm)
      (oref client session))))
 
@@ -525,12 +525,12 @@ back."
 ;;; Starting communication with a kernel
 
 (cl-defmethod jupyter-start-channels ((client jupyter-kernel-client))
-  (jupyter-connect-client (oref client kcomm) client))
+  (jupyter-comm-add-handler (oref client kcomm) client))
 
 (cl-defmethod jupyter-stop-channels ((client jupyter-kernel-client))
   "Stop any running channels of CLIENT."
   (when (slot-boundp client 'kcomm)
-    (jupyter-disconnect-client (oref client kcomm) client)))
+    (jupyter-comm-remove-handler (oref client kcomm) client)))
 
 (cl-defmethod jupyter-channels-running-p ((client jupyter-kernel-client))
   "Are any channels of CLIENT running?"

jupyter-comm-layer.el

@@ -31,10 +31,10 @@
 ;; A specific kernel communication layer (kcomm for short) is implemented by
 ;; extending the methods: `jupyter-comm-start', `jupyter-comm-stop',
 ;; `jupyter-comm-alive-p',`jupyter-event-handler', `jupyter-send', and possibly
-;; `jupyter-initialize-connection'.
+;; `jupyter-comm-initialize'.
 ;;
-;; A client registers with the kcomm by calling `jupyter-connect-client' and
-;; de-registers with `jupyter-disconnect-client'.  The communication layer deals
+;; A client registers with the kcomm by calling `jupyter-comm-add-handler' and
+;; de-registers with `jupyter-comm-remove-handler'.  The communication layer deals
 ;; with "events" which are just lists with an identifying symbol as the head
 ;; element.  Events that occur on the communication layer meant for clients,
 ;; e.g. a message received by a kernel or notification that a message was sent
@@ -63,16 +63,16 @@
   :group 'jupyter)
 
 (defclass jupyter-comm-layer ()
-  ((clients :type list :initform nil))
+  ((handlers :type list :initform nil))
   :abstract t)
 
-(defmacro jupyter-comm-client-loop (comm client &rest body)
-  "Loop over COMM's clients, binding each to CLIENT before evaluating BODY."
+(defmacro jupyter-comm-handler-loop (comm handler &rest body)
+  "Loop over COMM's handlers, binding each to HANDLER before evaluating BODY."
   (declare (indent 2))
-  (let ((clients (make-symbol "clients")))
-    `(let ((,clients (oref ,comm clients)))
-       (while ,clients
-         (when-let* ((,client (jupyter-weak-ref-resolve (pop ,clients))))
+  (let ((handlers (make-symbol "handlers")))
+    `(let ((,handlers (oref ,comm handlers)))
+       (while ,handlers
+         (when-let* ((,handler (jupyter-weak-ref-resolve (pop ,handlers))))
            ,@body)))))
 
 ;;; `jupyter-comm-layer'
@@ -86,14 +86,26 @@
 (cl-defgeneric jupyter-comm-alive-p ((comm jupyter-comm-layer))
   "Return non-nil if communication has started on COMM.")
 
-(cl-defgeneric jupyter-connect-client ((comm jupyter-comm-layer) obj)
+(define-obsolete-function-alias 'jupyter-connect-client 'jupyter-comm-add-handler "0.8.2"
   "Register OBJ to receive events from COMM.
 By default, on the first OBJ connected, `jupyter-comm-start' is
 called if needed.  This means that a call to
-`jupyter-initialize-connection' should precede a call to
-`jupyter-connect-client'.")
+`jupyter-comm-initialize' should precede a call to
+`jupyter-add-handler'.")
 
-(cl-defgeneric jupyter-disconnect-client ((comm jupyter-comm-layer) obj)
+(cl-defgeneric jupyter-comm-add-handler ((comm jupyter-comm-layer) obj)
+  "Register OBJ to receive events from COMM.
+By default, on the first OBJ connected, `jupyter-comm-start' is
+called if needed.  This means that a call to
+`jupyter-comm-initialize' should precede a call to
+`jupyter-add-handler'.")
+
+(define-obsolete-function-alias 'jupyter-disconnect-client 'jupyter-comm-remove-handler "0.8.2"
+  "De-register OBJ from receiving events from COMM.
+By default, on the last OBJ removed, `jupyter-comm-stop' is
+called if needed.")
+
+(cl-defgeneric jupyter-comm-remove-handler ((comm jupyter-comm-layer) obj)
   "De-register OBJ from receiving events from COMM.
 By default, on the last OBJ removed, `jupyter-comm-stop' is
 called if needed.")
@@ -112,10 +124,17 @@ buffer.")
   "Send EVENT to the underlying kernel using COMM."
   (error "Subclasses need to override this method"))
 
-(cl-defgeneric jupyter-initialize-connection ((comm jupyter-comm-layer) &rest _ignore)
+(define-obsolete-function-alias 'jupyter-initialize-connection 'jupyter-comm-initialize "0.8.2"
+  "Register OBJ to receive events from COMM.
+By default, on the first OBJ connected, `jupyter-comm-start' is
+called if needed.  This means that a call to
+`jupyter-comm-initialize' should precede a call to
+`jupyter-add-handler'.")
+
+(cl-defgeneric jupyter-comm-initialize ((comm jupyter-comm-layer) &rest _ignore)
   "Initialize communication on COMM.")
 
-(cl-defmethod jupyter-initialize-connection ((comm jupyter-comm-layer) &rest _ignore)
+(cl-defmethod jupyter-comm-initialize ((comm jupyter-comm-layer) &rest _ignore)
   "Raise an error if COMM is already alive."
   (when (jupyter-comm-alive-p comm)
     (error "Can't initialize a live comm")))
@@ -131,42 +150,42 @@ buffer.")
 (cl-defmethod jupyter-channel-alive-p ((_comm jupyter-comm-layer) _channel)
   (error "Need to implement"))
 
-(cl-defmethod jupyter-connect-client ((comm jupyter-comm-layer) obj)
-  (unless (cl-loop for ref in (oref comm clients)
+(cl-defmethod jupyter-comm-add-handler ((comm jupyter-comm-layer) obj)
+  (unless (cl-loop for ref in (oref comm handlers)
                    thereis (eq (jupyter-weak-ref-resolve ref) obj))
-    (push (jupyter-weak-ref obj) (oref comm clients)))
-  ;; Remove any garbage collected clients
-  (oset comm clients
+    (push (jupyter-weak-ref obj) (oref comm handlers)))
+  ;; Remove any garbage collected handlers
+  (oset comm handlers
         (cl-remove-if-not #'jupyter-weak-ref-resolve
-                          (oref comm clients)))
+                          (oref comm handlers)))
   (unless (jupyter-comm-alive-p comm)
     (jupyter-comm-start comm)))
 
-(cl-defmethod jupyter-disconnect-client ((comm jupyter-comm-layer) obj)
-  (oset comm clients
+(cl-defmethod jupyter-comm-remove-handler ((comm jupyter-comm-layer) obj)
+  (oset comm handlers
         (cl-remove-if (lambda (ref)
                         (let ((deref (jupyter-weak-ref-resolve ref)))
                           (or (eq deref obj) (null deref))))
-                      (oref comm clients))))
+                      (oref comm handlers))))
 
 (cl-defmethod jupyter-event-handler ((comm jupyter-comm-layer) event)
-  "Broadcast EVENT to all clients registered to receive them on COMM."
-  ;; TODO: Dynamically cleanup list of garbage collected clients when looping
+  "Broadcast EVENT to all handlers registered to receive them on COMM."
+  ;; TODO: Dynamically cleanup list of garbage collected handlers when looping
   ;; over it.
-  (jupyter-comm-client-loop comm client
-    (run-at-time 0 nil #'jupyter-event-handler client event)))
+  (jupyter-comm-handler-loop comm handler
+    (run-at-time 0 nil #'jupyter-event-handler handler event)))
 
 ;;; `jupyter-comm-autostop'
 
 (defclass jupyter-comm-autostop ()
   ()
   :abstract t
-  :documentation "Stop the comm when the last client disconnects.")
+  :documentation "Stop the comm when the last handler disconnects.")
 
-(cl-defmethod jupyter-disconnect-client :after ((comm jupyter-comm-autostop) _client)
-  "Stop COMM when there are no clients."
+(cl-defmethod jupyter-comm-remove-handler :after ((comm jupyter-comm-autostop) _handler)
+  "Stop COMM when there are no handlers."
   (when (and (jupyter-comm-alive-p comm)
-             (zerop (length (oref comm clients))))
+             (zerop (length (oref comm handlers))))
     (jupyter-comm-stop comm)))
 
 ;;; `jupyter-hb-comm'

jupyter-kernel-process-manager.el

@@ -234,7 +234,7 @@ connect to MANAGER's kernel."
         (oset client kcomm (make-instance
                             'jupyter-channel-ioloop-comm
                             :ioloop-class 'jupyter-zmq-channel-ioloop))
-        (jupyter-initialize-connection client (oref kernel session))))))
+        (jupyter-comm-initialize client (oref kernel session))))))
 
 (cl-defmethod jupyter-start-kernel :after ((manager jupyter-kernel-process-manager) &rest _args)
   (with-slots (kernel) manager

jupyter-repl.el

@@ -2236,7 +2236,7 @@ interactively, DISPLAY the new REPL buffer as well."
     (oset client kcomm (make-instance
                         'jupyter-channel-ioloop-comm
                         :ioloop-class 'jupyter-zmq-channel-ioloop))
-    (jupyter-initialize-connection client file-or-plist)
+    (jupyter-comm-initialize client file-or-plist)
     (jupyter-start-channels client)
     (jupyter-hb-unpause client)
     (jupyter-bootstrap-repl client repl-name associate-buffer display)))

jupyter-server.el

@@ -274,7 +274,7 @@ ID.  Send EVENT, with the kernel ID excluded, to a client whose
 kernel has a matching ID."
   (let ((kernel-id (cadr event)))
     (setq event (cons (car event) (cddr event)))
-    (jupyter-comm-client-loop comm client
+    (jupyter-comm-handler-loop comm client
       (when (equal kernel-id (oref (oref client kernel) id))
         ;; TODO: Since the event handlers of CLIENT will eventually call the
         ;; `jupyter-handle-message' of a `jupyter-kernel-client' we really
@@ -333,14 +333,14 @@ with default `jupyter-api-authentication-method'"))
                        :ws-headers (jupyter-api-auth-headers comm)))
     (cl-call-next-method)))
 
-(cl-defmethod jupyter-connect-client ((comm jupyter-server)
+(cl-defmethod jupyter-comm-add-handler ((comm jupyter-server)
                                       (kcomm jupyter-server-kernel-comm))
   (cl-call-next-method)
   (with-slots (id) (oref kcomm kernel)
     (unless (jupyter-server-kernel-connected-p comm id)
       (jupyter-server--connect-channels comm id))))
 
-(cl-defmethod jupyter-disconnect-client ((comm jupyter-server)
+(cl-defmethod jupyter-comm-remove-handler ((comm jupyter-server)
                                          (kcomm jupyter-server-kernel-comm))
   (with-slots (id) (oref kcomm kernel)
     (when (jupyter-server-kernel-connected-p comm id)
@@ -400,11 +400,11 @@ kernel associated with COMM, then COMM's `jupyter-event-handler'
 will receive those events."
   (with-slots (server) (oref comm kernel)
     (jupyter-comm-start server)
-    (jupyter-connect-client server comm)))
+    (jupyter-comm-add-handler server comm)))
 
 (cl-defmethod jupyter-comm-stop ((comm jupyter-server-kernel-comm) &rest _ignore)
   "Disconnect COMM from receiving server events."
-  (jupyter-disconnect-client (oref (oref comm kernel) server) comm))
+  (jupyter-comm-remove-handler (oref (oref comm kernel) server) comm))
 
 (cl-defmethod jupyter-send ((comm jupyter-server-kernel-comm) event-type &rest event)
   "Use COMM to send an EVENT to the server with type, EVENT-TYPE.
@@ -422,7 +422,7 @@ ID of the kernel associated with COMM."
           (oref kernel server)
           (oref kernel id))
          (catch 'member
-           (jupyter-comm-client-loop (oref kernel server) client
+           (jupyter-comm-handler-loop (oref kernel server) client
              (when (eq client comm)
                (throw 'member t)))))))
 
@@ -660,7 +660,7 @@ see ‘jupyter-make-client’."
          (manager (jupyter-server-kernel-manager :kernel kernel)))
     ;; Needs to be started before calling `jupyter-make-client' since that
     ;; method will send a request to start a websocket channel to the kernel.
-    ;; FIXME: This should be done in a `jupyter-initialize-connection' method,
+    ;; FIXME: This should be done in a `jupyter-comm-initialize' method,
     ;; but first that method needs to be generalize in `jupyter-client.el'
     (unless (jupyter-kernel-alive-p manager)
       (jupyter-start-kernel manager))

jupyter-zmq-channel-comm.el

@@ -126,7 +126,7 @@
     (if (eq channel :hb) (jupyter-start-channel (oref comm hb))
       (jupyter-start-channel (plist-get (oref comm channels) channel)))))
 
-(cl-defmethod jupyter-initialize-connection ((comm jupyter-zmq-channel-comm)
+(cl-defmethod jupyter-comm-initialize ((comm jupyter-zmq-channel-comm)
                                              (session jupyter-session))
   (cl-call-next-method)
   (let ((endpoints (jupyter-session-endpoints session)))

test/jupyter-server-test.el

@@ -277,7 +277,7 @@
           (let ((kcomm (jupyter-server-kernel-comm
                         :kernel kernel)))
             (should-not (jupyter-server-kernel-connected-p server id))
-            (jupyter-connect-client server kcomm)
+            (jupyter-comm-add-handler server kcomm)
             (should (jupyter-server-kernel-connected-p server id))
             (should (jupyter-comm-alive-p kcomm))
             (jupyter-comm-stop kcomm)
@@ -386,7 +386,7 @@
             (should (jupyter-comm-alive-p (oref manager comm)))
             (should (slot-boundp client 'kcomm))
             (should (eq (oref manager comm) (oref client kcomm)))
-            (jupyter-comm-client-loop (oref client kcomm) c
+            (jupyter-comm-handler-loop (oref client kcomm) c
               (should (eq c client)))
             (should (equal (jupyter-eval "1 + 1") "2")))
         (jupyter-shutdown-kernel manager)))))