deprecate Oval (#10256)

bokeh/models/glyphs.py

@@ -80,6 +80,7 @@
     ScalarLineProps,
     TextProps,
 )
+from ..util.deprecation import deprecated
 from .glyph import (
     ConnectedXYGlyph,
     FillGlyph,
@@ -792,6 +793,10 @@ class Oval(XYGlyph, LineGlyph, FillGlyph):
 
     '''
 
+    def __init__(self, **kwargs):
+        deprecated("'Oval' is deprecated and will be removed in Bokeh 3.0, use the Ellipse glyph instead")
+        super().__init__(**kwargs)
+
     __example__ = "examples/reference/models/Oval.py"
 
     # a canonical order for positional args that can be used for any

examples/models/file/glyphs.py

@@ -3,10 +3,10 @@
 from bokeh.document import Document
 from bokeh.embed import file_html
 from bokeh.models import (AnnularWedge, Annulus, Arc, Asterisk, Bezier, Circle,
-                          CircleCross, CircleX, Column, ColumnDataSource, Cross, Dash,
-                          Diamond, DiamondCross, Grid, Hex, HoverTool, ImageURL,
-                          InvertedTriangle, Line, LinearAxis, MultiLine,
-                          MultiPolygons, Oval, Panel, Paragraph, Patch, Patches, Plot,
+                          CircleCross, CircleX, Column, ColumnDataSource, Cross,
+                          Dash, Diamond, DiamondCross, Ellipse, Grid, Hex, HoverTool,
+                          ImageURL, InvertedTriangle, Line, LinearAxis, MultiLine,
+                          MultiPolygons, Panel, Paragraph, Patch, Patches, Plot,
                           Quad, Quadratic, Ray, Rect, Segment, Square, SquareCross,
                           SquareX, Tabs, Text, Triangle, Wedge, X,)
 from bokeh.resources import INLINE
@@ -49,11 +49,11 @@ def screen(value):
     ("annulus", Annulus(x="x", y="y", inner_radius=screen(10), outer_radius=screen(20), fill_color="#7FC97F")),
     ("arc", Arc(x="x", y="y", radius=screen(20), start_angle=0.6, end_angle=4.1, line_color="#BEAED4", line_width=3)),
     ("bezier", Bezier(x0="x", y0="y", x1="xp02", y1="y", cx0="xp01", cy0="yp01", cx1="xm01", cy1="ym01", line_color="#D95F02", line_width=2)),
+    ("ellipse", Ellipse(x="x", y="y", width=screen(15), height=screen(25), angle=-0.7, fill_color="#1D91C0")),
     ("image_url",  ImageURL(x="x", y="y", w=0.4, h=0.4, url=dict(value="https://static.bokeh.org/logos/logo.png"), anchor="center")),
     ("line", Line(x="x", y="y", line_color="#F46D43")),
     ("multi_line", MultiLine(xs="xs", ys="ys", line_color="#8073AC", line_width=2)),
     ("multi_polygons", MultiPolygons(xs="xsss", ys="ysss", line_color="#8073AC", fill_color="#FB9A99", line_width=2)),
-    ("oval", Oval(x="x", y="y", width=screen(15), height=screen(25), angle=-0.7, fill_color="#1D91C0")),
     ("patch", Patch(x="x", y="y", fill_color="#A6CEE3")),
     ("patches", Patches(xs="xs", ys="ys", fill_color="#FB9A99")),
     ("quad", Quad(left="x", right="xp01", top="y", bottom="ym01", fill_color="#B3DE69")),

examples/plotting/file/glyphs.py

@@ -63,11 +63,6 @@
     color="#FB9A99")
 children.append(p)
 
-p = figure(title="oval")
-p.oval(x, y, 15, 25, angle=-0.7, color="#1D91C0",
-       width_units="screen", height_units="screen")
-children.append(p)
-
 p = figure(title="patch")
 p.patch(x, y, color="#A6CEE3")
 children.append(p)

sphinx/source/docs/releases/2.2.0.rst

@@ -19,3 +19,8 @@ And several other bug fixes and docs additions. For full details see the
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Implement ``Glyph.scenterxy()`` instead.
+
+``Oval`` glyph deprecated
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use ``Ellipse`` instead.

sphinx/source/docs/user_guide/examples/graph_customize.py

@@ -1,7 +1,7 @@
 import math
 
 from bokeh.io import output_file, show
-from bokeh.models import GraphRenderer, Oval, StaticLayoutProvider
+from bokeh.models import Ellipse, GraphRenderer, StaticLayoutProvider
 from bokeh.palettes import Spectral8
 from bokeh.plotting import figure
 
@@ -15,7 +15,7 @@
 
 graph.node_renderer.data_source.add(node_indices, 'index')
 graph.node_renderer.data_source.add(Spectral8, 'color')
-graph.node_renderer.glyph = Oval(height=0.1, width=0.2, fill_color='color')
+graph.node_renderer.glyph = Ellipse(height=0.1, width=0.2, fill_color='color')
 
 graph.edge_renderer.data_source.data = dict(
     start=[0]*N,

sphinx/source/docs/user_guide/examples/graph_static_paths.py

@@ -1,7 +1,7 @@
 import math
 
 from bokeh.io import output_file, show
-from bokeh.models import GraphRenderer, Oval, StaticLayoutProvider
+from bokeh.models import Ellipse, GraphRenderer, StaticLayoutProvider
 from bokeh.palettes import Spectral8
 from bokeh.plotting import figure
 
@@ -15,7 +15,7 @@
 
 graph.node_renderer.data_source.add(node_indices, 'index')
 graph.node_renderer.data_source.add(Spectral8, 'color')
-graph.node_renderer.glyph = Oval(height=0.1, width=0.2, fill_color="color")
+graph.node_renderer.glyph = Ellipse(height=0.1, width=0.2, fill_color="color")
 
 graph.edge_renderer.data_source.data = dict(
     start=[0]*N,

sphinx/source/docs/user_guide/graph.rst

@@ -13,7 +13,7 @@ The key feature of the ``GraphRenderer`` is that it maintains separate
 sub-GlyphRenderers for the graph nodes and the graph edges. This allows for
 customizing the nodes by modifying the GraphRenderer's ``node_renderer``
 property. It's possible to replace the default Circle node glyph with any
-XYGlyph instance, for example a Rect or Oval glyph. Similarly, the style
+XYGlyph instance, for example a Rect or Ellipse glyph. Similarly, the style
 properties of the edges can modified through the ``edge_renderer`` property.
 The edge glyph is currently limited to a MultiLine glyph.
 
@@ -32,16 +32,16 @@ tooltips.
 
 Here's a code snippet that:
 
-- replaces the node glyph with an Oval
-- sets the ``height`` and ``width`` attributes of the Oval as scalar values
-- sets the ``fill_color`` attribute of the Oval as a vectorized field and adds
+- replaces the node glyph with an Ellipse
+- sets the ``height`` and ``width`` attributes of the Ellipse as scalar values
+- sets the ``fill_color`` attribute of the Ellipse as a vectorized field and adds
   the values to the node data source.
 
 .. code-block:: python
 
     import math
     from bokeh.plotting import figure
-    from bokeh.models import GraphRenderer, Oval
+    from bokeh.models import GraphRenderer, Ellipse
     from bokeh.palettes import Spectral8
 
     N = 8
@@ -52,7 +52,7 @@ Here's a code snippet that:
 
     graph = GraphRenderer()
 
-    graph.node_renderer.glyph = Oval(height=0.1, width=0.2, fill_color="fill_color")
+    graph.node_renderer.glyph = Ellipse(height=0.1, width=0.2, fill_color="fill_color")
     graph.node_renderer.data_source.data = dict(
         index=node_indices,
         fill_color=Spectral8)

sphinx/source/docs/user_guide/plotting.rst

@@ -350,25 +350,18 @@ potentially with a corresponding label or color.
 .. bokeh-plot:: docs/user_guide/examples/plotting_multipolygons.py
     :source-position: above
 
-.. _userguide_plotting_ovals_ellipses:
+.. _userguide_plotting_ellipses:
 
-Ovals and Ellipses
-~~~~~~~~~~~~~~~~~~
-
-The |oval| glyph method accepts the same properties as |rect|, but renders
-oval shapes:
+Ellipses
+~~~~~~~~
 
-.. bokeh-plot:: docs/user_guide/examples/plotting_ovals.py
-    :source-position: above
-
-The |ellipse| glyph accepts the same properties as |oval| and |rect| but
-renders ellipse shapes, which are different from oval ones. In particular,
-the same value for width and height will render a circle using the |ellipse|
-glyph but not the |oval| one:
+The |ellipse| glyph method accepts the same properties as |rect|, but renders
+ellipse shapes:
 
 .. bokeh-plot:: docs/user_guide/examples/plotting_ellipses.py
     :source-position: above
 
+
 .. _userguide_plotting_images:
 
 Images
@@ -639,7 +632,6 @@ below:
 .. |line|              replace:: :func:`~bokeh.plotting.Figure.line`
 .. |multi_line|        replace:: :func:`~bokeh.plotting.Figure.multi_line`
 .. |multi_polygons|    replace:: :func:`~bokeh.plotting.Figure.multi_polygons`
-.. |oval|              replace:: :func:`~bokeh.plotting.Figure.oval`
 .. |patch|             replace:: :func:`~bokeh.plotting.Figure.patch`
 .. |patches|           replace:: :func:`~bokeh.plotting.Figure.patches`
 .. |plus|              replace:: :func:`~bokeh.plotting.Figure.plus`