refactor(scales): parameterize scale_discrete over its guide type

Make scale_discrete generic over GuideTypeT instead of hardcoding
guide: Literal["legend"] | None, and add OptionalLegend,
OptionalColorbar and OptionalGuide aliases to _runtime_typing.
Each discrete scale subclass now declares its own guide field.

Behavior change: identity scales for color, fill, shape, linetype
and alpha now default to guide="legend" (size and stroke keep None).
scale_position_discrete declares guide: None as a field instead of
assigning it in __post_init__.

Author: has2k1

plotnine/scales/_runtime_typing.py

@@ -5,7 +5,7 @@
 the documentation.
 """
 
-from typing import Callable, Sequence, Type, TypeAlias, TypeVar
+from typing import Callable, Literal, Sequence, Type, TypeAlias, TypeVar
 
 from mizani.transforms import trans
 
@@ -51,6 +51,10 @@
 
 TransUser: TypeAlias = trans | str | Type[trans] | None
 
+OptionalLegend: TypeAlias = Literal["legend"] | None
+OptionalColorbar: TypeAlias = Literal["colorbar"] | None
+OptionalGuide: TypeAlias = Literal["legend", "colorbar"] | None
+
 RangeT = TypeVar("RangeT", bound=Range)
 BreaksUserT = TypeVar("BreaksUserT")
 LimitsUserT = TypeVar("LimitsUserT")

plotnine/scales/scale_alpha.py

@@ -1,9 +1,10 @@
 from dataclasses import KW_ONLY, InitVar, dataclass
-from typing import Literal
 from warnings import warn
 
 import numpy as np
 
+from plotnine.scales._runtime_typing import OptionalLegend
+
 from .._utils.registry import alias
 from ..exceptions import PlotnineWarning
 from .scale_continuous import scale_continuous
@@ -12,7 +13,7 @@
 
 
 @dataclass
-class scale_alpha(scale_continuous[Literal["legend"]]):
+class scale_alpha(scale_continuous[OptionalLegend]):
     """
     Continuous Alpha Scale
     """
@@ -25,7 +26,7 @@ class scale_alpha(scale_continuous[Literal["legend"]]):
     """
 
     _: KW_ONLY
-    guide: Literal["legend"] = "legend"
+    guide: OptionalLegend = "legend"
 
     def __post_init__(self, range):
         from mizani.palettes import rescale_pal
@@ -40,11 +41,14 @@ class scale_alpha_continuous(scale_alpha):
 
 
 @dataclass
-class scale_alpha_ordinal(scale_discrete):
+class scale_alpha_ordinal(scale_discrete[OptionalLegend]):
     """
     Ordinal Alpha Scale
     """
 
+    _: KW_ONLY
+    guide: OptionalLegend = "legend"
+
     _aesthetics = ["alpha"]
     range: InitVar[tuple[float, float]] = (0.1, 1)
     """
@@ -89,7 +93,7 @@ class scale_alpha_datetime(scale_datetime):
     """
 
     _: KW_ONLY
-    guide: Literal["legend"] = "legend"
+    guide: OptionalLegend = "legend"
 
     def __post_init__(
         self,

plotnine/scales/scale_color.py

@@ -4,6 +4,8 @@
 from typing import Literal, Sequence
 from warnings import warn
 
+from plotnine.scales._runtime_typing import OptionalGuide, OptionalLegend
+
 from .._utils.registry import alias
 from ..exceptions import PlotnineWarning
 from .scale_continuous import scale_continuous
@@ -12,13 +14,14 @@
 
 
 @dataclass
-class _scale_color_discrete(scale_discrete):
+class _scale_color_discrete(scale_discrete[OptionalLegend]):
     """
     Base class for all discrete color scales
     """
 
     _aesthetics = ["color"]
     _: KW_ONLY
+    guide: OptionalLegend = "legend"
     na_value: str = "#7F7F7F"
     """
     Color of missing values.
@@ -27,15 +30,15 @@ class _scale_color_discrete(scale_discrete):
 
 @dataclass
 class _scale_color_continuous(
-    scale_continuous[Literal["legend", "colorbar"] | None],
+    scale_continuous[OptionalGuide],
 ):
     """
     Base class for all continuous color scales
     """
 
     _aesthetics = ["color"]
     _: KW_ONLY
-    guide: Literal["legend", "colorbar"] | None = "colorbar"
+    guide: OptionalGuide = "colorbar"
     na_value: str = "#7F7F7F"
     """
     Color of missing values.
@@ -563,7 +566,7 @@ class scale_color_datetime(scale_datetime, scale_color_cmap):  # pyright: ignore
     """
 
     _: KW_ONLY
-    guide: Literal["legend", "colorbar"] | None = "colorbar"
+    guide: OptionalGuide = "colorbar"
 
     def __post_init__(
         self,

plotnine/scales/scale_discrete.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Literal, Sequence
+from typing import TYPE_CHECKING, Any, Sequence
 
 import numpy as np
 import pandas as pd
@@ -11,7 +11,7 @@
 from .._utils import match
 from ..iapi import range_view, scale_view
 from ._expand import expand_range
-from ._runtime_typing import DiscreteBreaksUser, DiscreteLimitsUser
+from ._runtime_typing import DiscreteBreaksUser, DiscreteLimitsUser, GuideTypeT
 from .range import RangeDiscrete
 from .scale import scale
 
@@ -29,7 +29,7 @@ class scale_discrete(
         RangeDiscrete,
         DiscreteBreaksUser,
         DiscreteLimitsUser,
-        Literal["legend"] | None,
+        GuideTypeT,
     ]
 ):
     """
@@ -69,8 +69,6 @@ class scale_discrete(
     `nan` is always placed on the right.
     """
 
-    guide: Literal["legend"] | None = "legend"
-
     def __post_init__(self):
         super().__post_init__()
         self._range = RangeDiscrete()

plotnine/scales/scale_identity.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
 from dataclasses import KW_ONLY, dataclass
-from typing import TYPE_CHECKING, Literal
+from typing import TYPE_CHECKING
+
+from plotnine.scales._runtime_typing import OptionalLegend
 
 from .._utils.registry import alias
 from .scale_continuous import scale_continuous
@@ -37,14 +39,14 @@ def train(self, x, drop=False):
 
 
 @dataclass
-class scale_color_identity(MapTrainMixin, scale_discrete):
+class scale_color_identity(MapTrainMixin, scale_discrete[OptionalLegend]):
     """
     No color scaling
     """
 
     _aesthetics = ["color"]
     _: KW_ONLY
-    guide: Literal["legend"] | None = None
+    guide: OptionalLegend = "legend"
 
 
 @dataclass
@@ -54,67 +56,61 @@ class scale_fill_identity(scale_color_identity):
     """
 
     _aesthetics = ["fill"]
-    _: KW_ONLY
-    guide: Literal["legend"] | None = None
 
 
 @dataclass
-class scale_shape_identity(MapTrainMixin, scale_discrete):
+class scale_shape_identity(MapTrainMixin, scale_discrete[OptionalLegend]):
     """
     No shape scaling
     """
 
     _aesthetics = ["shape"]
     _: KW_ONLY
-    guide: Literal["legend"] | None = None
+    guide: OptionalLegend = "legend"
 
 
 @dataclass
-class scale_linetype_identity(MapTrainMixin, scale_discrete):
+class scale_linetype_identity(MapTrainMixin, scale_discrete[OptionalLegend]):
     """
     No linetype scaling
     """
 
     _aesthetics = ["linetype"]
     _: KW_ONLY
-    guide: Literal["legend"] | None = None
+    guide: OptionalLegend = "legend"
 
 
 @dataclass
-class scale_alpha_identity(
-    MapTrainMixin, scale_continuous[Literal["legend"] | None]
-):
+class scale_alpha_identity(MapTrainMixin, scale_continuous[OptionalLegend]):
     """
     No alpha scaling
     """
 
     _aesthetics = ["alpha"]
     _: KW_ONLY
-    guide: Literal["legend"] | None = None
+    guide: OptionalLegend = "legend"
 
 
 @dataclass
-class scale_size_identity(
-    MapTrainMixin, scale_continuous[Literal["legend"] | None]
-):
+class scale_size_identity(MapTrainMixin, scale_continuous[OptionalLegend]):
     """
     No size scaling
     """
 
     _aesthetics = ["size"]
     _: KW_ONLY
-    guide: Literal["legend"] | None = None
+    guide: OptionalLegend = None
 
 
 @dataclass
-class scale_stroke_identity(MapTrainMixin, scale_discrete):
+class scale_stroke_identity(MapTrainMixin, scale_discrete[OptionalLegend]):
     """
     No stroke scaling
     """
 
     _aesthetics = ["stroke"]
     _: KW_ONLY
-    guide: Literal["legend"] | None = None
+    guide: OptionalLegend = None
 
 
 # American to British spelling

plotnine/scales/scale_linetype.py

@@ -1,6 +1,8 @@
-from dataclasses import dataclass
+from dataclasses import KW_ONLY, dataclass
 from warnings import warn
 
+from plotnine.scales._runtime_typing import OptionalLegend
+
 from .._utils.registry import alias
 from ..exceptions import PlotnineError, PlotnineWarning
 from .scale_continuous import scale_continuous
@@ -10,7 +12,7 @@
 
 
 @dataclass
-class scale_linetype(scale_discrete):
+class scale_linetype(scale_discrete[OptionalLegend]):
     """
     Scale for line patterns
 
@@ -24,6 +26,9 @@ class scale_linetype(scale_discrete):
 
     _aesthetics = ["linetype"]
 
+    _: KW_ONLY
+    guide: OptionalLegend = "legend"
+
     def __post_init__(self):
         from mizani.palettes import manual_pal
 

plotnine/scales/scale_manual.py

@@ -5,13 +5,15 @@
 from typing import Any, Sequence
 from warnings import warn
 
+from plotnine.scales._runtime_typing import OptionalLegend
+
 from .._utils.registry import alias
 from ..exceptions import PlotnineWarning
 from .scale_discrete import scale_discrete
 
 
 @dataclass
-class _scale_manual(scale_discrete):
+class _scale_manual(scale_discrete[OptionalLegend]):
     """
     Abstract class for manual scales
     """
@@ -20,6 +22,8 @@ class _scale_manual(scale_discrete):
     """
     Exact values the scale should map to.
     """
+    _: KW_ONLY
+    guide: OptionalLegend = "legend"
 
     def __post_init__(self, values):
         from collections.abc import Iterable, Sized

plotnine/scales/scale_shape.py

@@ -1,6 +1,8 @@
-from dataclasses import InitVar, dataclass
+from dataclasses import KW_ONLY, InitVar, dataclass
 from warnings import warn
 
+from plotnine.scales._runtime_typing import OptionalLegend
+
 from .._utils.registry import alias
 from ..exceptions import PlotnineError, PlotnineWarning
 from .scale_continuous import scale_continuous
@@ -50,7 +52,7 @@
 
 
 @dataclass
-class scale_shape(scale_discrete):
+class scale_shape(scale_discrete[OptionalLegend]):
     """
     Scale for shapes
     """
@@ -61,6 +63,8 @@ class scale_shape(scale_discrete):
     If `True`, then all shapes will have no interiors
     that can be a filled.
     """
+    _: KW_ONLY
+    guide: OptionalLegend = "legend"
 
     def __post_init__(self, unfilled):
         from mizani.palettes import manual_pal