Finalize sub-plot API and add documentation

bokehjs/src/lib/models/scales/scale.ts

@@ -1,6 +1,5 @@
 import {Transform} from "../transforms/transform"
 import {Range} from "../ranges/range"
-import {Range1d} from "../ranges/range1d"
 import type {Arrayable, FloatArray} from "core/types"
 import {ScreenArray} from "core/types"
 import type * as p from "core/properties"
@@ -10,7 +9,7 @@ export namespace Scale {
 
   export type Props = Transform.Props & {
     source_range: p.Property<Range>
-    target_range: p.Property<Range1d>
+    target_range: p.Property<Range>
   }
 }
 
@@ -26,7 +25,7 @@ export abstract class Scale<T = number> extends Transform<T, number> {
   static {
     this.internal<Scale.Props>(({Ref}) => ({
       source_range: [ Ref(Range) ],
-      target_range: [ Ref(Range1d) ],
+      target_range: [ Ref(Range) ],
     }))
   }
 

src/bokeh/core/property/singletons.py

@@ -18,19 +18,28 @@
 # Imports
 #-----------------------------------------------------------------------------
 
-#-----------------------------------------------------------------------------
-# Globals and constants
-#-----------------------------------------------------------------------------
+# Standard library imports
+from typing import TYPE_CHECKING, TypeVar, Union
+
+if TYPE_CHECKING:
+    from typing_extensions import TypeAlias
 
 #-----------------------------------------------------------------------------
-# General API
+# Globals and constants
 #-----------------------------------------------------------------------------
 
 __all__ = (
     "Intrinsic",
+    "Optional",
     "Undefined",
 )
 
+T = TypeVar("T")
+
+#-----------------------------------------------------------------------------
+# General API
+#-----------------------------------------------------------------------------
+
 #-----------------------------------------------------------------------------
 # Dev API
 #-----------------------------------------------------------------------------
@@ -49,6 +58,8 @@ def __repr__(self) -> str:
 
 Undefined = UndefinedType()
 
+Optional: TypeAlias = Union[T, UndefinedType]
+
 class IntrinsicType:
     """ Indicates usage of the intrinsic default value of a property. """
 

src/bokeh/plotting/_figure.py

@@ -44,6 +44,7 @@
     TimeDelta,
     Tuple,
 )
+from ..core.property.singletons import Optional, Undefined
 from ..models import (
     ColumnDataSource,
     CoordinateMapping,
@@ -224,12 +225,37 @@
 
     def subplot(self,
             *,
-            x_source: Range | None = None, y_source: Range | None = None,
-            x_scale: Scale | None = None, y_scale: Scale | None = None,
-            x_target: Range, y_target: Range,
+            x_source: Optional[Range] = Undefined,
+            y_source: Optional[Range] = Undefined,
+            x_scale: Optional[Scale] = Undefined,
+            y_scale: Optional[Scale] = Undefined,
+            x_target: Range,
+            y_target: Range,
         ) -> GlyphAPI:
-        """ Create a new sub-coordinate system and expose a plotting API. """
-        coordinates = CoordinateMapping(x_source=x_source, y_source=y_source, x_target=x_target, y_target=y_target)
+        """
+        Create a new sub-coordinate system and expose the plotting API.
+
+        Example:
+
+            .. bokeh-plot::
+                :source-position: above
+
+                from bokeh.plotting import figure, show
+
+                p = figure(x_range=[0, 10], y_range=[0, 10])
+                p.subplot(x_target=[0, 1], y_target=p.y_range).circle([0, 1, 2], [0, 1, 2])
+                p.subplot(x_target=[2, 3], y_target=p.y_range).circle([0, 1, 2], [0, 1, 2])
+
+                show(p)
+        """
+        coordinates = CoordinateMapping(
+            x_source=x_source,
+            y_source=y_source,
+            x_scale=x_scale,
+            y_scale=y_scale,
+            x_target=x_target,
+            y_target=y_target,
+        )
         return GlyphAPI(self, coordinates)
 
     def hexbin(self, x, y, size, orientation="pointytop", palette="Viridis256", line_color=None, fill_color=None, aspect_scale=1, **kwargs):

src/bokeh/plotting/glyph_api.py

@@ -46,7 +46,7 @@
 #-----------------------------------------------------------------------------
 
 class GlyphAPI:
-    """ """
+    """ Generalized glyph/plotting API for figures and sub-plots. """
 
     @property
     def plot(self) -> Plot | None: