Repository: bokeh/bokeh

Issue:
Deprecate output_server
`output_server` has a number of deficiencies relative to native apps or even `bokeh.client`. I propose to deprecate it and remove it entirely before `1.0`

ping @bokeh/dev 



Discussion:
I presume it's possible to detect bokeh being run in a notebook? If so, we could remove `output_*()` functions altogether.

> I presume it's possible to detect bokeh being run in a notebook?

Not possible to know if bokeh is running from a notebook or another client... the kernel does not know anything about the frontend. Several frontends could be potentially "tied" to the same kernel which makes the mapping prone to errors. For instance, I can start a notebook which connect the web frontend with a specific kernel, then I attach a jupyter console to the same kernel, if I ask the kernel from where I am triggering the command, and we previously "linked" it to the web client, it would tell me that I am/running from the web client but I actually used the jupyter console...

Right, the only way to "know" is to try and publish something and try to see if it fails or not. We in fact did just that a few years ago. Unfortunately it had some bad unintended side-effect (I don't remember the details) and had to be reverted in a hurry in the next release.

Also `output_file` and `output_notebook` are  used ubiquitously. Removing them would break mountains of code. But `output_server` I think we could nip in the bud if we do it soon. 

@bokeh/dev any more thoughts? There seems to be a sudden spike in questions around `output_server` so I am definitely inclined to proceed with a deprecation. `output_server` is basically useless except for static plots and leads people to confusion when callbacks "don't work."

@bryevdv, my understanding of server and its various entry points is insufficient for advice. Though I will vote +1 just for reducing the number of entry points.

No one chimed in to oppose, so I will make this a task 


Resolving patch:
diff --git a/bokeh/io.py b/bokeh/io.py
--- a/bokeh/io.py
+++ b/bokeh/io.py
@@ -181,6 +181,7 @@ def output_notebook(resources=None, verbose=False, hide_banner=False, load_timeo
 # usually we default session_id to "generate a random one" but
 # here we default to a hardcoded one. This is to support local
 # usage e.g. with a notebook.
+@deprecated("Bokeh 0.12.3", "bokeh.client sessions (described at http://bokeh.pydata.org/en/latest/docs/user_guide/server.html#connecting-with-bokeh-client)")
 def output_server(session_id=DEFAULT_SESSION_ID, url="default", app_path="/", autopush=False):
     """ Configure the default output state to push its document to a
     session on a Bokeh server.
diff --git a/examples/plotting/server/hover.py b/examples/plotting/server/hover.py
deleted file mode 100644
--- a/examples/plotting/server/hover.py
+++ /dev/null
@@ -1,50 +0,0 @@
-# You must first run "bokeh serve" to view this example
-
-import itertools
-
-import numpy as np
-
-from bokeh.models import HoverTool
-from bokeh.plotting import ColumnDataSource, figure, show, output_server
-
-TOOLS="crosshair,pan,wheel_zoom,box_zoom,reset,hover,save"
-
-xx, yy = np.meshgrid(range(0,101,4), range(0,101,4))
-x = xx.flatten()
-y = yy.flatten()
-N = len(x)
-inds = [str(i) for i in np.arange(N)]
-radii = np.random.random(size=N)*0.4 + 1.7
-colors = [
-    "#%02x%02x%02x" % (int(r), int(g), 150) for r, g in zip(50+2*x, 30+2*y)
-]
-
-source = ColumnDataSource(data=dict(
-    x=x,
-    y=y,
-    radius=radii,
-    colors=colors,
-    foo=list(itertools.permutations("abcdef"))[:N],
-    bar=np.random.normal(size=N),
-))
-
-p = figure(title="Hoverful Scatter", tools=TOOLS)
-
-p.circle(x, y, radius=radii, source=source,
-         fill_color=colors, fill_alpha=0.6, line_color=None)
-
-p.text(x, y, text=inds, alpha=0.5, text_font_size="5pt",
-       text_baseline="middle", text_align="center")
-
-hover = p.select_one(HoverTool).tooltips = [
-    ("index", "$index"),
-    ("(x,y)", "($x, $y)"),
-    ("radius", "@radius"),
-    ("fill color", "$color[hex, swatch]:fill_color"),
-    ("foo", "@foo"),
-    ("bar", "@bar"),
-]
-
-output_server("hover")
-
-show(p)  # open a browser


Test patch: