{"action":"created","comment":{"url":"https://api.github.com/repos/nteract/enchannel/pulls/comments/55925359","id":55925359,"diff_hunk":"@@ -70,6 +70,108 @@ Messages observed from these Subjects are all immutable, not by convention but t\n \n Note that [heartbeat](http://jupyter-client.readthedocs.org/en/latest/messaging.html#heartbeat-for-kernels) is not included above, primarily because it's being thought of as something that may end up being deprecated.\n \n+## What's in this repo?\n+\n+In addition to the spec doc itself (the text above) this repo contains convenience functions for enchannel implementations and consumers.  To use these functions install this package with npm\n+\n+    npm install enchannel\n+\n+The utility functions included are described below\n+\n+#### isChildMessage\n+Checks to see if one message is child to another.  Accepts two arguments, parent and child, both of which are [Jupyter message objects](https://ipython.org/ipython-doc/3/development/messaging.html#general-message-format).  To use as a conditional:\n+\n+```js\n+const enchannel = require('enchannel');\n+if (enchannel.isChildMessage(parent, child)) {\n+  console.log('is child');\n+}\n+```\n+\n+It will probably make more sense to use it as an observable filter.  In the example below, `parent` is a [Jupyter message object](https://ipython.org/ipython-doc/3/development/messaging.html#general-message-format) and `channels.iopub` is an RxJS observable:\n+\n+```js\n+const enchannel = require('enchannel');\n+const isChildMessage = enchannel.isChildMessage.bind(null, parent);\n+const childMessages = channels.iopub.filter(isChildMessage);\n+```\n+\n+#### createMessage\n+Creates a [Jupyter message object](https://ipython.org/ipython-doc/3/development/messaging.html#general-message-format).  Accepts 3 arguments:\n+\n+ - username, string  \n+ - session, string,  guid unique to the current session  \n+ - msg_type: string, type of the message getting sent  \n+\n+The following is a full example that shows how connection may happen, how you'd setup the session and username, and then create and send a shutdown request:\n+\n+```js\n+// The method to connect is specific to the enchannel backend implementation\n+enchannelBackend.connect().then(channels => {\n+\n+  // Created once with the channels\n+  const uuid = require('node-uuid');\n+  const session = uuid.v4();\n+  const username = process.env.LOGNAME || process.env.USER ||\n+    process.env.LNAME || process.env.USERNAME;\n+\n+  // Create the shutdown request method\n+  const enchannel = require('enchannel');\n+  const shutdownRequest = enchannel.createMessage(username, session, 'shutdown_request');\n+  shutdownRequest.content = { restart: false };\n+\n+  // Send it\n+  // Before sending, don't forget to subscribe to the channel you are sending on!  In practice\n+  // there is more code involved here, because you'd want to filter the messages your subscribing\n+  // to for messages that are child to the one that you send.\n+  channels.shell.subscribe(content => { /* ... */ });\n+  channels.shell.next(shutdownRequest);\n+});\n+```\n+\n+#### shutdownRequest\n+Sends a [shutdown request Jupyter message](https://ipython.org/ipython-doc/3/development/messaging.html#kernel-shutdown) to the kernel and completes the observables.  Accepts 3 arguments:\n+\n+ - username, string  \n+ - session, string,  guid unique to the current session  \n+ - channels: object, enchannel channels object\n+ - restart: optional boolean, whether the shutdown request is actually a restart request\n+\n+The following full example shows how this method would be used:\n+\n+```js\n+// The method to connect is specific to the enchannel backend implementation\n+enchannelBackend.connect().then(channels => {","path":"README.md","position":75,"original_position":75,"commit_id":"768206a4fda5091dbca84b0a6bfd9ca1aee49eb4","original_commit_id":"768206a4fda5091dbca84b0a6bfd9ca1aee49eb4","user":{"login":"jdfreder","id":3292874,"avatar_url":"https://avatars.githubusercontent.com/u/3292874?v=3","gravatar_id":"","url":"https://api.github.com/users/jdfreder","html_url":"https://github.com/jdfreder","followers_url":"https://api.github.com/users/jdfreder/followers","following_url":"https://api.github.com/users/jdfreder/following{/other_user}","gists_url":"https://api.github.com/users/jdfreder/gists{/gist_id}","starred_url":"https://api.github.com/users/jdfreder/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jdfreder/subscriptions","organizations_url":"https://api.github.com/users/jdfreder/orgs","repos_url":"https://api.github.com/users/jdfreder/repos","events_url":"https://api.github.com/users/jdfreder/events{/privacy}","received_events_url":"https://api.github.com/users/jdfreder/received_events","type":"User","site_admin":false},"body":":+1: ","created_at":"2016-03-12T18:17:47Z","updated_at":"2016-03-12T18:17:47Z","html_url":"https://github.com/nteract/enchannel/pull/12#discussion_r55925359","pull_request_url":"https://api.github.com/repos/nteract/enchannel/pulls/12","_links":{"self":{"href":"https://api.github.com/repos/nteract/enchannel/pulls/comments/55925359"},"html":{"href":"https://github.com/nteract/enchannel/pull/12#discussion_r55925359"},"pull_request":{"href":"https://api.github.com/repos/nteract/enchannel/pulls/12"}}},"pull_request":{"url":"https://api.github.com/repos/nteract/enchannel/pulls/12","id":62646837,"html_url":"https://github.com/nteract/enchannel/pull/12","diff_url":"https://github.com/nteract/enchannel/pull/12.diff","patch_url":"https://github.com/nteract/enchannel/pull/12.patch","issue_url":"https://api.github.com/repos/nteract/enchannel/issues/12","number":12,"state":"closed","locked":false,"title":"Add information about the convenience API to the docs","user":{"login":"jdfreder","id":3292874,"avatar_url":"https://avatars.githubusercontent.com/u/3292874?v=3","gravatar_id":"","url":"https://api.github.com/users/jdfreder","html_url":"https://github.com/jdfreder","followers_url":"https://api.github.com/users/jdfreder/followers","following_url":"https://api.github.com/users/jdfreder/following{/other_user}","gists_url":"https://api.github.com/users/jdfreder/gists{/gist_id}","starred_url":"https://api.github.com/users/jdfreder/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jdfreder/subscriptions","organizations_url":"https://api.github.com/users/jdfreder/orgs","repos_url":"https://api.github.com/users/jdfreder/repos","events_url":"https://api.github.com/users/jdfreder/events{/privacy}","received_events_url":"https://api.github.com/users/jdfreder/received_events","type":"User","site_admin":false},"body":"","created_at":"2016-03-12T17:32:28Z","updated_at":"2016-03-12T18:17:47Z","closed_at":"2016-03-12T17:36:03Z","merged_at":"2016-03-12T17:36:03Z","merge_commit_sha":"124bcc4648cbcff9f4c68b807a75f28dad728cc4","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/nteract/enchannel/pulls/12/commits","review_comments_url":"https://api.github.com/repos/nteract/enchannel/pulls/12/comments","review_comment_url":"https://api.github.com/repos/nteract/enchannel/pulls/comments{/number}","comments_url":"https://api.github.com/repos/nteract/enchannel/issues/12/comments","statuses_url":"https://api.github.com/repos/nteract/enchannel/statuses/768206a4fda5091dbca84b0a6bfd9ca1aee49eb4","head":{"label":"jdfreder:moardocs","ref":"moardocs","sha":"768206a4fda5091dbca84b0a6bfd9ca1aee49eb4","user":{"login":"jdfreder","id":3292874,"avatar_url":"https://avatars.githubusercontent.com/u/3292874?v=3","gravatar_id":"","url":"https://api.github.com/users/jdfreder","html_url":"https://github.com/jdfreder","followers_url":"https://api.github.com/users/jdfreder/followers","following_url":"https://api.github.com/users/jdfreder/following{/other_user}","gists_url":"https://api.github.com/users/jdfreder/gists{/gist_id}","starred_url":"https://api.github.com/users/jdfreder/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jdfreder/subscriptions","organizations_url":"https://api.github.com/users/jdfreder/orgs","repos_url":"https://api.github.com/users/jdfreder/repos","events_url":"https://api.github.com/users/jdfreder/events{/privacy}","received_events_url":"https://api.github.com/users/jdfreder/received_events","type":"User","site_admin":false},"repo":{"id":53277761,"name":"enchannel","full_name":"jdfreder/enchannel","owner":{"login":"jdfreder","id":3292874,"avatar_url":"https://avatars.githubusercontent.com/u/3292874?v=3","gravatar_id":"","url":"https://api.github.com/users/jdfreder","html_url":"https://github.com/jdfreder","followers_url":"https://api.github.com/users/jdfreder/followers","following_url":"https://api.github.com/users/jdfreder/following{/other_user}","gists_url":"https://api.github.com/users/jdfreder/gists{/gist_id}","starred_url":"https://api.github.com/users/jdfreder/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jdfreder/subscriptions","organizations_url":"https://api.github.com/users/jdfreder/orgs","repos_url":"https://api.github.com/users/jdfreder/repos","events_url":"https://api.github.com/users/jdfreder/events{/privacy}","received_events_url":"https://api.github.com/users/jdfreder/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/jdfreder/enchannel","description":":currency_exchange: standardizing how a frontend communicates with a kernel","fork":true,"url":"https://api.github.com/repos/jdfreder/enchannel","forks_url":"https://api.github.com/repos/jdfreder/enchannel/forks","keys_url":"https://api.github.com/repos/jdfreder/enchannel/keys{/key_id}","collaborators_url":"https://api.github.com/repos/jdfreder/enchannel/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/jdfreder/enchannel/teams","hooks_url":"https://api.github.com/repos/jdfreder/enchannel/hooks","issue_events_url":"https://api.github.com/repos/jdfreder/enchannel/issues/events{/number}","events_url":"https://api.github.com/repos/jdfreder/enchannel/events","assignees_url":"https://api.github.com/repos/jdfreder/enchannel/assignees{/user}","branches_url":"https://api.github.com/repos/jdfreder/enchannel/branches{/branch}","tags_url":"https://api.github.com/repos/jdfreder/enchannel/tags","blobs_url":"https://api.github.com/repos/jdfreder/enchannel/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/jdfreder/enchannel/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/jdfreder/enchannel/git/refs{/sha}","trees_url":"https://api.github.com/repos/jdfreder/enchannel/git/trees{/sha}","statuses_url":"https://api.github.com/repos/jdfreder/enchannel/statuses/{sha}","languages_url":"https://api.github.com/repos/jdfreder/enchannel/languages","stargazers_url":"https://api.github.com/repos/jdfreder/enchannel/stargazers","contributors_url":"https://api.github.com/repos/jdfreder/enchannel/contributors","subscribers_url":"https://api.github.com/repos/jdfreder/enchannel/subscribers","subscription_url":"https://api.github.com/repos/jdfreder/enchannel/subscription","commits_url":"https://api.github.com/repos/jdfreder/enchannel/commits{/sha}","git_commits_url":"https://api.github.com/repos/jdfreder/enchannel/git/commits{/sha}","comments_url":"https://api.github.com/repos/jdfreder/enchannel/comments{/number}","issue_comment_url":"https://api.github.com/repos/jdfreder/enchannel/issues/comments{/number}","contents_url":"https://api.github.com/repos/jdfreder/enchannel/contents/{+path}","compare_url":"https://api.github.com/repos/jdfreder/enchannel/compare/{base}...{head}","merges_url":"https://api.github.com/repos/jdfreder/enchannel/merges","archive_url":"https://api.github.com/repos/jdfreder/enchannel/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/jdfreder/enchannel/downloads","issues_url":"https://api.github.com/repos/jdfreder/enchannel/issues{/number}","pulls_url":"https://api.github.com/repos/jdfreder/enchannel/pulls{/number}","milestones_url":"https://api.github.com/repos/jdfreder/enchannel/milestones{/number}","notifications_url":"https://api.github.com/repos/jdfreder/enchannel/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/jdfreder/enchannel/labels{/name}","releases_url":"https://api.github.com/repos/jdfreder/enchannel/releases{/id}","deployments_url":"https://api.github.com/repos/jdfreder/enchannel/deployments","created_at":"2016-03-06T21:43:13Z","updated_at":"2016-03-01T19:55:55Z","pushed_at":"2016-03-12T18:06:48Z","git_url":"git://github.com/jdfreder/enchannel.git","ssh_url":"git@github.com:jdfreder/enchannel.git","clone_url":"https://github.com/jdfreder/enchannel.git","svn_url":"https://github.com/jdfreder/enchannel","homepage":"","size":29,"stargazers_count":0,"watchers_count":0,"language":null,"has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"nteract:master","ref":"master","sha":"06b0dace1fe8095351aac93dd4b1555411bb320a","user":{"login":"nteract","id":12401040,"avatar_url":"https://avatars.githubusercontent.com/u/12401040?v=3","gravatar_id":"","url":"https://api.github.com/users/nteract","html_url":"https://github.com/nteract","followers_url":"https://api.github.com/users/nteract/followers","following_url":"https://api.github.com/users/nteract/following{/other_user}","gists_url":"https://api.github.com/users/nteract/gists{/gist_id}","starred_url":"https://api.github.com/users/nteract/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/nteract/subscriptions","organizations_url":"https://api.github.com/users/nteract/orgs","repos_url":"https://api.github.com/users/nteract/repos","events_url":"https://api.github.com/users/nteract/events{/privacy}","received_events_url":"https://api.github.com/users/nteract/received_events","type":"Organization","site_admin":false},"repo":{"id":49481165,"name":"enchannel","full_name":"nteract/enchannel","owner":{"login":"nteract","id":12401040,"avatar_url":"https://avatars.githubusercontent.com/u/12401040?v=3","gravatar_id":"","url":"https://api.github.com/users/nteract","html_url":"https://github.com/nteract","followers_url":"https://api.github.com/users/nteract/followers","following_url":"https://api.github.com/users/nteract/following{/other_user}","gists_url":"https://api.github.com/users/nteract/gists{/gist_id}","starred_url":"https://api.github.com/users/nteract/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/nteract/subscriptions","organizations_url":"https://api.github.com/users/nteract/orgs","repos_url":"https://api.github.com/users/nteract/repos","events_url":"https://api.github.com/users/nteract/events{/privacy}","received_events_url":"https://api.github.com/users/nteract/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/nteract/enchannel","description":":currency_exchange: standardizing how a frontend communicates with a kernel","fork":false,"url":"https://api.github.com/repos/nteract/enchannel","forks_url":"https://api.github.com/repos/nteract/enchannel/forks","keys_url":"https://api.github.com/repos/nteract/enchannel/keys{/key_id}","collaborators_url":"https://api.github.com/repos/nteract/enchannel/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/nteract/enchannel/teams","hooks_url":"https://api.github.com/repos/nteract/enchannel/hooks","issue_events_url":"https://api.github.com/repos/nteract/enchannel/issues/events{/number}","events_url":"https://api.github.com/repos/nteract/enchannel/events","assignees_url":"https://api.github.com/repos/nteract/enchannel/assignees{/user}","branches_url":"https://api.github.com/repos/nteract/enchannel/branches{/branch}","tags_url":"https://api.github.com/repos/nteract/enchannel/tags","blobs_url":"https://api.github.com/repos/nteract/enchannel/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/nteract/enchannel/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/nteract/enchannel/git/refs{/sha}","trees_url":"https://api.github.com/repos/nteract/enchannel/git/trees{/sha}","statuses_url":"https://api.github.com/repos/nteract/enchannel/statuses/{sha}","languages_url":"https://api.github.com/repos/nteract/enchannel/languages","stargazers_url":"https://api.github.com/repos/nteract/enchannel/stargazers","contributors_url":"https://api.github.com/repos/nteract/enchannel/contributors","subscribers_url":"https://api.github.com/repos/nteract/enchannel/subscribers","subscription_url":"https://api.github.com/repos/nteract/enchannel/subscription","commits_url":"https://api.github.com/repos/nteract/enchannel/commits{/sha}","git_commits_url":"https://api.github.com/repos/nteract/enchannel/git/commits{/sha}","comments_url":"https://api.github.com/repos/nteract/enchannel/comments{/number}","issue_comment_url":"https://api.github.com/repos/nteract/enchannel/issues/comments{/number}","contents_url":"https://api.github.com/repos/nteract/enchannel/contents/{+path}","compare_url":"https://api.github.com/repos/nteract/enchannel/compare/{base}...{head}","merges_url":"https://api.github.com/repos/nteract/enchannel/merges","archive_url":"https://api.github.com/repos/nteract/enchannel/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/nteract/enchannel/downloads","issues_url":"https://api.github.com/repos/nteract/enchannel/issues{/number}","pulls_url":"https://api.github.com/repos/nteract/enchannel/pulls{/number}","milestones_url":"https://api.github.com/repos/nteract/enchannel/milestones{/number}","notifications_url":"https://api.github.com/repos/nteract/enchannel/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/nteract/enchannel/labels{/name}","releases_url":"https://api.github.com/repos/nteract/enchannel/releases{/id}","deployments_url":"https://api.github.com/repos/nteract/enchannel/deployments","created_at":"2016-01-12T06:54:21Z","updated_at":"2016-03-12T05:50:26Z","pushed_at":"2016-03-12T18:07:19Z","git_url":"git://github.com/nteract/enchannel.git","ssh_url":"git@github.com:nteract/enchannel.git","clone_url":"https://github.com/nteract/enchannel.git","svn_url":"https://github.com/nteract/enchannel","homepage":"","size":29,"stargazers_count":0,"watchers_count":0,"language":"JavaScript","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":3,"mirror_url":null,"open_issues_count":0,"forks":3,"open_issues":0,"watchers":0,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/nteract/enchannel/pulls/12"},"html":{"href":"https://github.com/nteract/enchannel/pull/12"},"issue":{"href":"https://api.github.com/repos/nteract/enchannel/issues/12"},"comments":{"href":"https://api.github.com/repos/nteract/enchannel/issues/12/comments"},"review_comments":{"href":"https://api.github.com/repos/nteract/enchannel/pulls/12/comments"},"review_comment":{"href":"https://api.github.com/repos/nteract/enchannel/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/nteract/enchannel/pulls/12/commits"},"statuses":{"href":"https://api.github.com/repos/nteract/enchannel/statuses/768206a4fda5091dbca84b0a6bfd9ca1aee49eb4"}}}}